plane-local-mcp

MCP (Model Context Protocol) local para Plane Community Edition self-hosted.

Usa a API pública /api/v1/.../issues/ (compatível com Plane CE). Útil para listar projetos, issues, estados, labels, cycles e buscar itens pelo identificador humano (PROJECT-N, ex.: CKTPC-838).

Pré-requisitos

• Python >= 3.10
• uv instalado e no PATH
• Instância Plane CE acessível + API key

Instalação

git clone https://github.com/JonatanCosta/plane-local-mcp.git
cd plane-local-mcp
uv sync

Anote o caminho absoluto do clone (ex.: /Users/voce/plane-local-mcp). Ele será usado nas configs abaixo.

Variáveis de ambiente

Variável	Obrigatória	Descrição
PLANE_API_KEY	sim	API key do Plane
PLANE_WORKSPACE_SLUG	sim	Slug do workspace
PLANE_BASE_URL	sim	URL base da instância (sem /api)

Exemplo:

export PLANE_API_KEY="plane_api_..."
export PLANE_WORKSPACE_SLUG="meu-workspace"
export PLANE_BASE_URL="https://plane.exemplo.com"

Cursor

Edite ~/.cursor/mcp.json (ou Settings → MCP → Add server) e adicione:

{
  "mcpServers": {
    "plane": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABS/PATH/plane-local-mcp",
        "plane-local-mcp"
      ],
      "env": {
        "PLANE_API_KEY": "plane_api_...",
        "PLANE_WORKSPACE_SLUG": "meu-workspace",
        "PLANE_BASE_URL": "https://plane.exemplo.com"
      }
    }
  }
}

Substitua /ABS/PATH/plane-local-mcp pelo caminho absoluto do repositório. Reinicie o Cursor (ou recarregue os MCPs) e confira se o servidor plane aparece com as tools.

Claude Desktop

1. Abra Settings → Developer → Edit Config (cria o arquivo se ainda não existir).

2. Edite claude_desktop_config.json:

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

{
  "mcpServers": {
    "plane": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/ABS/PATH/plane-local-mcp",
        "plane-local-mcp"
      ],
      "env": {
        "PLANE_API_KEY": "plane_api_...",
        "PLANE_WORKSPACE_SLUG": "meu-workspace",
        "PLANE_BASE_URL": "https://plane.exemplo.com"
      }
    }
  }
}

3. Feche completamente o Claude Desktop e abra de novo.
4. No chat, o ícone de ferramentas (martelo) deve listar as tools do Plane.

Dica: se uv não for encontrado, use o caminho absoluto do binário (ex.: /Users/voce/.local/bin/uv).

Claude Code (CLI)

claude mcp add plane --env PLANE_API_KEY=plane_api_... \
  --env PLANE_WORKSPACE_SLUG=meu-workspace \
  --env PLANE_BASE_URL=https://plane.exemplo.com \
  -- uv run --directory /ABS/PATH/plane-local-mcp plane-local-mcp

Ou edite ~/.claude/settings.json / .claude/settings.json com o mesmo bloco mcpServers do Cursor.

Codex (CLI / IDE)

Edite ~/.codex/config.toml (ou .codex/config.toml no projeto, se ele estiver trusted):

[mcp_servers.plane]
command = "uv"
args = [
  "run",
  "--directory",
  "/ABS/PATH/plane-local-mcp",
  "plane-local-mcp",
]

[mcp_servers.plane.env]
PLANE_API_KEY = "plane_api_..."
PLANE_WORKSPACE_SLUG = "meu-workspace"
PLANE_BASE_URL = "https://plane.exemplo.com"

Alternativa via CLI:

codex mcp add plane --env PLANE_API_KEY=plane_api_... \
  --env PLANE_WORKSPACE_SLUG=meu-workspace \
  --env PLANE_BASE_URL=https://plane.exemplo.com \
  -- uv run --directory /ABS/PATH/plane-local-mcp plane-local-mcp

Em uma sessão Codex, use /mcp para validar que o servidor conectou.

Tools disponíveis

Tool	Descrição
get_instance_info	Base URL, workspace e estilo de API
list_projects	Lista projetos do workspace
retrieve_project	Projeto por UUID
list_states	Estados (colunas) do projeto
list_labels	Labels do projeto
list_modules	Modules do projeto
list_cycles	Cycles do projeto
list_issues	Issues do projeto (/issues/)
retrieve_issue	Issue por UUID
get_issue_by_identifier	Issue por PROJECT-N (ex.: CKTPC-838)
list_issue_children	Filhos de um épico/issue
update_issue	Edita título, descrição, prioridade e/ou status
add_issue_to_cycle	Adiciona issue a um cycle
remove_issue_from_cycle	Remove issue de um cycle

Exemplos de edição

update_issue(identifier="CKTPC-844", name="Novo título")
update_issue(identifier="CKTPC-844", description="Texto simples da descrição")
update_issue(identifier="CKTPC-844", state_name="Em Execução")
add_issue_to_cycle(identifier="CKTPC-844", cycle_name="Payment Sprint - 23")

Notas:

• Descrição no Plane usa HTML (description_html). Se passar description em texto puro, o MCP converte para HTML mínimo.
• Status e cycle aceitam UUID (state_id / cycle_id) ou nome (state_name / cycle_name).
• Cycle não entra no PATCH da issue: a API exige POST .../cycles/{id}/cycle-issues/.

Desenvolvimento

uv sync
uv run plane-local-mcp

O servidor fala MCP via stdio.

Licença

MIT