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

Abra Settings → Developer → Edit Config (cria o arquivo se ainda não existir).
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"
      }
    }
  }
}

Feche completamente o Claude Desktop e abra de novo.
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

plane-local-mcp

plane-local-mcp

Pré-requisitos

Instalação

Variáveis de ambiente

Cursor

Claude Desktop

Claude Code (CLI)

Codex (CLI / IDE)

Tools disponíveis

Exemplos de edição

Desenvolvimento

Licença

Latest Blog Posts

MCP directory API