Plane MCP Server - Python Implementation

Plane's Model Context Protocol Server - Python реализация 🔌 ⌨️ 🔥

Предоставляет 48 инструментов для работы с проектами, задачами, модулями и циклами в Plane.

Оригинальный проект: makeplane/plane-mcp-server (TypeScript) plane.so | Topics: model-context-protocol mcp-server python fastmcp

📚 Документация

• [ARCHITECTURE.md](docs/ARCHITECTURE.md) - Архитектура и сравнение stdio vs
• [USAGE.md](docs/USAGE.md) - Подробная инструкция по использованию NPM пакета
• [COPILOT_USAGE.md](docs/COPILOT_USAGE.md) - Как использовать с GitHub Copilot в VSCode
• [CONTRIBUTING.md](CONTRIBUTING.md) - Руководство для контрибьюторов
• [CHANGELOG.md](CHANGELOG.md) - История изменений
• [NPM_PUBLISH.md](docs/NPM_PUBLISH.md) - Публикация форка в NPM

✨ Возможности

• ✅ 48 инструментов - полное покрытие Plane API
• ✅ Transport - HTTP сервер для удалённого доступа
• ✅ stdio Transport - для локальной интеграции с Claude Desktop
• ✅ Полный CRUD для Issues, Projects, Modules, Cycles
• ✅ Metadata Management - полное управление типами задач, метками, статусами
• ✅ Module/Cycle Issues - управление задачами в модулях и циклах
• ✅ Worklogs - отслеживание времени работы
• ✅ Issue Comments - работа с комментариями
• ✅ Readable Identifiers - поддержка PROJECT-123 формата
• ✅ Асинхронная архитектура - быстрая обработка запросов
• ✅ Docker Ready - готовые конфигурации для контейнеризации

📊 Краткий обзор инструментов

User (2 tools)

• get_current_user - информация о текущем пользователе
• get_workspace_members - список участников workspace

Metadata (14 tools)

Issue Types (4):

• get_issue_type, create_issue_type, update_issue_type, delete_issue_type

States (5):

• list_states, get_state, create_state, update_state, delete_state

Labels (5):

• list_labels, get_label, create_label, update_label, delete_label

Projects (3 tools)

• get_projects - список всех проектов
• create_project - создание нового проекта
• list_project_issues - список задач проекта

Issues (7 tools)

• get_issue - детали конкретной задачи
• get_issue_using_readable_identifier - получить задачу по читаемому ID (FIRST-123)
• create_issue - создание задачи
• update_issue - обновление задачи
• delete_issue - удаление задачи
• get_issue_comments - получить комментарии к задаче
• add_issue_comment - добавить комментарий к задаче

Modules (5 tools)

• list_modules - список модулей проекта
• get_module - детали модуля
• create_module - создание модуля
• update_module - обновление модуля
• delete_module - удаление модуля

Module Issues (3 tools)

• list_module_issues - список задач в модуле
• add_module_issues - добавить задачи в модуль
• delete_module_issue - удалить задачу из модуля

Cycles (5 tools)

• list_cycles - список циклов проекта
• get_cycle - детали цикла
• create_cycle - создание цикла
• update_cycle - обновление цикла
• delete_cycle - удаление цикла

Cycle Issues (4 tools)

• list_cycle_issues - список задач в цикле
• add_cycle_issues - добавить задачи в цикл
• delete_cycle_issue - удалить задачу из цикла
• transfer_cycle_issues - перенести задачи из одного цикла в другой

Worklogs (5 tools)

• get_issue_worklogs - список рабочих логов задачи
• get_total_worklogs - общее время логов проекта
• create_worklog - создать рабочий лог
• update_worklog - обновить рабочий лог
• delete_worklog - удалить рабочий лог

Всего: 48 инструментов

🚀 Быстрый старт

Вариант 1: NPM (рекомендуется для локального использования)

Требования: Node.js 18+, uv

✅ Пакет опубликован в NPM: @mikey-semy/plane-mcp

# Использование без установки (npx)
npx -y @mikey-semy/plane-mcp

# Или глобальная установка
npm install -g @mikey-semy/plane-mcp
plane-mcp

Переменные окружения:

# Windows PowerShell
$env:PLANE_API_KEY="plane_xxxxxxxxxxxxxxxxxxxx"
$env:PLANE_WORKSPACE_SLUG="your-workspace-slug"
$env:PLANE_API_HOST_URL="https://api.plane.so/"  # опционально

# Linux/macOS
export PLANE_API_KEY="plane_xxxxxxxxxxxxxxxxxxxx"
export PLANE_WORKSPACE_SLUG="your-workspace-slug"
export PLANE_API_HOST_URL="https://api.plane.so/"  # опционально

Вариант 2: Docker (для продакшена)

1. Создайте .env файл:

cp .env.example .env

Отредактируйте .env и добавьте свои данные:

# Обязательные переменные
PLANE_API_KEY=plane_xxxxxxxxxxxxxxxxxxxx
PLANE_WORKSPACE_SLUG=your-workspace-slug

# Опциональные (значения по умолчанию)
PLANE_API_HOST_URL=https://api.plane.so/
MCP_HOST=0.0.0.0
MCP_PORT=8000

# Порт на хосте (если 8000 занят, измените на другой)
HOST_PORT=8000

Примечание: Если порт 8000 уже занят, измените HOST_PORT на другой (например, 8001, 9000).

2. Запуск с Docker Compose:

docker-compose up -d

Сервер будет доступен на http://localhost:HOST_PORT/ (по умолчанию http://localhost:8000/)

3. Проверка работы:

# Проверка здоровья контейнера
docker-compose ps

# Просмотр логов
docker-compose logs -f

# Остановка
docker-compose down

Локальная установка (для разработки)

Требования

• Python 3.12+
• uv (для управления пакетами)

Установка

# Установка uv (если ещё не установлен)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Клонирование и установка зависимостей
cd plane-mcp
uv sync

# Создание .env файла
cp .env.example .env
# Отредактируйте .env, добавьте свои ключи

# Запуск сервера
uv run plane-mcp

Конфигурация

Переменные окружения

Для продакшена: используйте .env.production с вашими настройками.

🌐 Развёртывание

Публичный NPM пакет

✅ Пакет опубликован и доступен: @mikey-semy/plane-mcp

Любой пользователь может использовать:

npx -y @mikey-semy/plane-mcp

Docker развёртывание

Используйте Docker Compose для продакшен развёртывания. Сервер будет доступен по HTTP на указанном порту.

Пример URL после развёртывания:

https://your-domain.com:9000/

Настройте свой домен в .env.production и используйте reverse proxy (Traefik/Nginx) для SSL.

#### ⚠️ Безопасность развёртывания

ВАЖНО: endpoint предоставляет полный доступ к вашему Plane API!

Рекомендуемые меры защиты:

1. 🔒 Не публикуйте URL публично - SSE endpoint содержит ваш API ключ
2. 🛡️ Используйте VPN - ограничьте доступ только для вашей сети
3. 🔐 Basic Auth - добавьте authentication на уровне Traefik/Nginx
4. 🌐 IP Whitelist - разрешите доступ только с определённых IP
5. 📝 Логирование - отслеживайте все подключения
6. 🔄 Регулярно ротируйте API ключи

Пример Traefik с Basic Auth:

labels:
  - "traefik.http.middlewares.auth.basicauth.users=user:$$apr1$$..."
  - "traefik.http.routers.mcp.middlewares=auth"

Для личного использования рекомендуем stdio, а не публичный SSE сервер.

Использование с MCP клиентами

FastMCP автоматически поддерживает:

• SSE (Server-Sent Events) - HTTP транспорт на http://host:port/sse
• stdio - стандартный ввод/вывод для локальных клиентов

#### 🤔 Какой вариант выбрать?

stdio (локальный) - рекомендуется:

• ✅ Можно работать с несколькими workspace одновременно
• ✅ Разные API ключи для разных workspace
• ✅ Полный контроль над конфигурацией
• ⚠️ Требует установку uv локально

SSE (удалённый) - для централизованного использования:

• ✅ Не требует Python/uv на клиентской машине
• ✅ Быстрое подключение (сервер уже работает)
• ✅ Единая конфигурация для команды
• ⚠️ Фиксированный workspace на сервере
• ⚠️ Требует сетевое подключение к серверу
• 🔒 Не публикуйте публичные URL - используйте VPN или authentication!

📖 Подробнее: COPILOT_USAGE.md

#### Подключение через VSCode

Добавьте конфигурацию в .vscode/mcp.json или mcp.json в корне проекта:

Вариант 1: NPM пакет (stdio) - для работы с разными workspace

Позволяет переключаться между workspace просто меняя env:

{
  "servers": {
    "plane-profitool": {
      "command": "npx",
      "args": ["-y", "@mikey-semy/plane-mcp"],
      "env": {
        "PLANE_API_KEY": "YOUR_PLANE_API_KEY",
        "PLANE_API_HOST_URL": "https://plane.equiply.ru/",
        "PLANE_WORKSPACE_SLUG": "profitool-store"
      }
    },
    "plane-another-project": {
      "command": "npx",
      "args": ["-y", "@mikey-semy/plane-mcp"],
      "env": {
        "PLANE_API_KEY": "YOUR_PLANE_API_KEY",
        "PLANE_API_HOST_URL": "https://plane.equiply.ru/",
        "PLANE_WORKSPACE_SLUG": "another-workspace"
      }
    }
  }
}

Вариант 2: Удалённое подключение (SSE)

Подключение к вашему развёрнутому серверу. Внимание: workspace фиксирован на сервере!

Без авторизации:

{
  "servers": {
    "plane": {
      "url": "https://your-mcp-server.example.com:9000/sse"
    }
  }
}

С Basic Auth (рекомендуется для production):

{
  "servers": {
    "plane": {
      "url": "https://mcp.plane.lol.ru:9000/sse",
      "headers": {
        "Authorization": "Basic YWRtaW46UlolXJlUGFzc3dvcmQxMjM="
      }
    }
  }
}

Примечание:

• Замените your-mcp-server.example.com на адрес вашего сервера.
• Для генерации Authorization заголовка см. _AUTH.md
• НЕ используйте формат `https://user:pass@host/` - не поддерживается клиентами MCP

Для работы с несколькими workspace через : разверните отдельный сервер для каждого workspace.

#### Подключение через Claude Desktop

Добавьте конфигурацию в claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Вариант 1: NPM пакет (рекомендуется)

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["-y", "@mikey-semy/plane-mcp"],
      "env": {
        "PLANE_API_KEY": "plane_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "your-workspace-slug",
        "PLANE_API_HOST_URL": "https://api.plane.so/"
      }
    }
  }
}

Вариант 2: Локальная установка (uv)

{
  "mcpServers": {
    "plane": {
      "command": "uv",
      "args": ["run", "plane-mcp"],
      "env": {
        "PLANE_API_KEY": "plane_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "your-workspace-slug",
        "PLANE_API_HOST_URL": "https://api.plane.so/"
      }
    }
  }
}

После сохранения конфигурации перезапустите VSCode или Claude Desktop.

Разработка

Структура проекта

plane-mcp/
├── src/
│   └── plane_mcp/
│       ├── __init__.py
│       ├── server.py          # Основной сервер
│       ├── schemas/           # Pydantic модели (новая структура)
│       │   ├── __init__.py
│       │   ├── base.py        # Базовые классы и миксины
│       │   ├── project.py     # Project
│       │   ├── issue.py       # Issue, IssueType
│       │   ├── module.py      # Module, ModuleIssue
│       │   ├── cycle.py       # Cycle, CycleIssue
│       │   ├── metadata.py    # State, Label
│       │   └── worklog.py     # IssueWorkLog
│       ├── common/
│       │   ├── request_helper.py  # HTTP клиент для Plane API
│       │   └── version.py
│       └── tools/
│           ├── cycle_issues.py
│           ├── cycles.py
│           ├── issue_comments.py
│           ├── issues.py
│           ├── metadata.py
│           ├── module_issues.py
│           ├── modules.py
│           ├── projects.py
│           ├── user.py
│           └── worklogs.py
├── pyproject.toml
├── Dockerfile
└── docker-compose.yml

Архитектура схем

Все Pydantic модели организованы с использованием наследования для DRY-кода:

Базовые классы (base.py):

• PlaneBaseModel - корневой класс с общими настройками
• TimestampedModel - добавляет created_at, updated_at
• AuditedModel - добавляет created_by, updated_by
• WorkspaceOwnedModel - добавляет workspace
• ProjectOwnedModel - добавляет project
• SoftDeletableModel - добавляет deleted_at
• ArchivableModel - добавляет archived_at
• ExternallyIdentifiableModel - добавляет external_id, external_source
• SortableModel - добавляет sort_order
• FullAuditModel - объединяет все вышеперечисленные + id

Доменные модели:

• project.py - Project (наследуется от FullAuditModel)
• issue.py - Issue, IssueType
• module.py - Module, ModuleIssue
• cycle.py - Cycle, CycleIssue
• metadata.py - State, Label
• worklog.py - IssueWorkLog

Каждая схема полностью документирована с описанием всех полей, типов и ограничений.

Запуск тестов

uv run pytest

Форматирование кода

uv run ruff check --fix
uv run ruff format

Получение API ключа Plane

1. Войдите в Plane
2. Перейдите в Settings → API Tokens
3. Создайте новый токен
4. Скопируйте и сохраните в .env или используйте как переменную окружения

📦 Публикация в NPM

Если вы хотите опубликовать свой форк пакета, следуйте инструкциям в NPM_PUBLISH.md.

Лицензия

MIT

Автор

Сгенерировано на основе официального Plane MCP Server