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 - Архитектура и сравнение stdio vs

• USAGE.md - Подробная инструкция по использованию NPM пакета

• COPILOT_USAGE.md - Как использовать с GitHub Copilot в VSCode

• CONTRIBUTING.md - Руководство для контрибьюторов

• CHANGELOG.md - История изменений

• NPM_PUBLISH.md - Публикация форка в NPM

Related MCP server: plane-mcp-server

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

• ✅ 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