Plane

Plane MCP-сервер

Сервер Model Context Protocol для Plane. Предоставляет AI-агенту инструменты для чтения и управления проектами, рабочими элементами, циклами, модулями, релизами, клиентами и другим.

Построен на FastMCP и официальном plane-sdk.

• 30 инструментов, по одному на ресурс Plane, охватывающих 207 операций
• Локально или удалённо — stdio, streamable HTTP, SSE
• Аутентификация через OAuth или API-ключ

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

Получите API-ключ в Plane: Настройки рабочего пространства → API-токены.

Добавьте это в конфигурацию вашего MCP-клиента:

{
  "mcpServers": {
    "plane": {
      "command": "uvx",
      "args": ["plane-mcp-server", "stdio"],
      "env": {
        "PLANE_API_KEY": "<your-api-key>",
        "PLANE_WORKSPACE_SLUG": "<your-workspace-slug>"
      }
    }
  }
}

uvx не требует установки. Требуется Python 3.10+.

Для самостоятельно размещённого Plane добавьте "PLANE_BASE_URL": "https://plane.example.com".

Транспорты

stdio — локально

Запускается как подпроцесс вашего MCP-клиента. Конфигурация показана выше; требуется PLANE_API_KEY и PLANE_WORKSPACE_SLUG.

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio

HTTP с OAuth — размещённый

https://mcp.plane.so/http/mcp

Поток OAuth обрабатывается при подключении; учётные данные в конфигурации не нужны. Для клиентов без встроенной поддержки удалённого MCP используйте мост с mcp-remote:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}

Требуется Node.js 22+.

HTTP с персональным токеном доступа — размещённый

https://mcp.plane.so/http/api-key/mcp

Заголовок	Значение
Authorization	Bearer <PAT>
X-Workspace-slug	<workspace-slug>

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <PAT>",
        "X-Workspace-slug": "<workspace-slug>"
      }
    }
  }
}

SSE — устаревший

https://mcp.plane.so/sse поддерживается только для обратной совместимости. Используйте HTTP-транспорт.

Инструменты

Сервер предоставляет 30 инструментов, по одному на ресурс. Каждый принимает параметр action, который выбирает операцию:

workitem(action="create", project_id=..., name="Fix login")
workitem(action="list", project_id=..., pql='state__group = "started"')
cycle(action="archive", project_id=..., cycle_id=...)

Описание каждого инструмента перечисляет его действия с обязательными и необязательными параметрами, поэтому каталог самодокументируется при вызове.

→ Полный справочник инструментов и действий

Запросы рабочих элементов

Список, подсчёт и поиск принимают PQL — язык запросов Plane:

workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")

Вызовите get_pql_reference для полного синтаксиса, операторов и примеров.

Переход с пооперационных инструментов

В более ранних версиях на каждую операцию API был отдельный инструмент. Существующие интеграции продолжают работать: 169 из 177 этих имён по-прежнему разрешаются в консолидированный инструмент, поэтому сохранённый промпт или скрипт, вызывающий create_work_item или list_cycles, не требует изменений. Они больше не рекламируются и сохраняют имена параметров, с которыми были выпущены (work_item_id, а не workitem_id).

Семь имён выбирали между двумя операциями с помощью параметра (manage_project_archive(archive=False)), что одна пара «инструмент-действие» воспроизвести не может; вызов такого имени сообщит вам его замену. get_pql_reference не изменился.

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

Аутентификация

Переменная	Требуется для	Назначение
PLANE_API_KEY	stdio	API-ключ
PLANE_WORKSPACE_SLUG	stdio	Целевое рабочее пространство
PLANE_BASE_URL	необязательно	URL API Plane (по умолчанию https://api.plane.so)

Удалённые транспорты несут учётные данные в соединении — поток OAuth или заголовки PAT — и не требуют ни одной из этих переменных.

Исходящий прокси для загрузки вложений

HTTP_PROXY / HTTPS_PROXY / NO_PROXY (и их формы в нижнем регистре) учитываются для загрузки вложения по URL (upload_from_url). Когда прокси применяется к данному запросу, именно прокси, а не этот сервер, является контролем SSRF для этого запроса: сервер не закрепляет и не проверяет разрешённый адрес цели самостоятельно, поскольку прокси подключается к цели и разрешает её независимо. Ограничьте NO_PROXY и политику исходящего трафика прокси соответствующим образом.

Самостоятельное размещение самого сервера:

Переменная	Назначение
PLANE_INTERNAL_BASE_URL	Внутренний URL для вызовов сервер-сервер, предпочтительнее PLANE_BASE_URL
REDIS_URL	Хранилище OAuth-токенов как один URL подключения (redis:// или rediss:// для TLS); имеет приоритет над хостом/портом
REDIS_HOST / REDIS_PORT	Хранилище OAuth-токенов; при отсутствии — в памяти
PLANE_OAUTH_PROVIDER_*	Учётные данные OAuth-клиента и базовый URL
MCP_PATH_PREFIX	Префикс пути для HTTP-маршрутов при размещении за прокси — /plane обслуживает /plane/http/mcp

URI перенаправления OAuth

OAuth-транспорты проверяют URI перенаправления каждого клиента по белому списку. Распространённые клиенты (Cursor, VS Code, Claude.ai, коннекторы ChatGPT, localhost) разрешены по умолчанию.

Чтобы добавить новый клиент без выпуска версии, добавьте шаблоны:

export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"

* соответствует любому порту, сегменту пути или поддомену. Держите хост закреплённым и используйте подстановочные знаки только для порта или пути.

Журналирование

Структурированный JSON. Каждый вызов инструмента записывает его имя, длительность, статус и — когда доступно — непрозрачный идентификатор пользователя и слаг рабочего пространства.

export LOG_USER_INFO=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

Только OAuth- и PAT-транспорты несут отображаемое имя; stdio не затрагивается.

Разработка

git clone https://github.com/makeplane/plane-mcp-server
cd plane-mcp-server
uv pip install -e ".[dev]"

Запустите сервер против рабочего пространства:

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
python -m plane_mcp http            # port 8211

Тесты, форматирование, линтер:

pytest                              # no network or credentials needed
ruff format plane_mcp/ tests/       # line length 120
ruff check plane_mcp/ tests/        # rules E, F, I, UP, B

Набор тестов полностью работает офлайн — каждое действие каждого ресурса выполняется против заглушки, которая связывает каждый вызов с подлинной сигнатурой plane-sdk. См. plane_mcp/tools/README.md.

Живые интеграционные тесты пропускаются, если не указать запущенный сервер:

export PLANE_TEST_API_KEY=... PLANE_TEST_WORKSPACE_SLUG=...
export PLANE_TEST_MCP_URL=http://localhost:8211    # optional; this is the default
pytest tests/test_integration.py -v

Они записывают реальные данные в это рабочее пространство.

Структура репозитория

Путь	Содержимое
plane_mcp/__main__.py	точка входа; выбирает транспорт из argv[1]
plane_mcp/server.py	по одной фабрике на транспорт
plane_mcp/client.py	преобразует учётные данные в клиент plane-sdk
plane_mcp/auth/	OAuth-провайдер и аутентификация по заголовкам
plane_mcp/tools/	поверхность инструментов: по одному модулю на ресурс Plane
plane_mcp/toolkit/	общие строительные блоки для поверхности инструментов
plane_mcp/pql_reference.py	справочник синтаксиса PQL, предоставляемый моделям

Участие

Приветствуются pull request. Пожалуйста, запустите pytest и ruff check перед отправкой; новые инструменты должны соответствовать инвариантам, описанным в plane_mcp/tools/README.md.

См. CONTRIBUTING.md и CODE_OF_CONDUCT.md.

Переход с Node.js-сервера

@makeplane/plane-mcp-server (Node.js) устарел и не поддерживается. Эта реализация на Python заменяет его.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

Замените command и args на конфигурацию stdio из Быстрого старта.

Лицензия

MIT — см. LICENSE.