plane-mcp

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

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

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

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

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

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

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

| Переменная | Описание | По умолчанию | Обязательная | |-----------|----------|--------------|--------------| | PLANE_API_KEY | API ключ Plane | - | ✅ | | PLANE_WORKSPACE_SLUG | Slug вашего workspace | - | ✅ | | PLANE_API_HOST_URL | URL Plane API | https://api.plane.so/ | ❌ | | MCP_HOST | Хост для HTTP сервера | 0.0.0.0 | ❌ | | MCP_PORT | Порт контейнера (внутренний) | 8000 | ❌ | | HOST_PORT | Порт хоста (внешний) для Docker | 8000 | ❌ |

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

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

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

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

Любой пользователь может использовать: ``bash 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: ```yaml 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](docs/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 фиксирован на сервере!

Без авторизации: ``json { "servers": { "plane": { "url": "https://your-mcp-server.example.com:9000/sse" } } } ``

С Basic Auth (рекомендуется для production): ``json { "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