Plane

oficial

O servidor MCP oficial do Plane fornece integração com as APIs do Plane, permitindo automação completa por IA de projetos, itens de trabalho, ciclos e muito mais do Plane.

GitHub

289

O que você pode fazer com Plane MCP?

Create work items — Create a work item in a project via workitem action create.
Query work items with PQL — List or count work items filtered by PQL (e.g., state, priority) using workitem actions list/count.
Get PQL reference — Ask for the full PQL syntax and operators via get_pql_reference.
Archive cycles — Archive a cycle using cycle action archive.

Documentação

Plane MCP Server

Um servidor Model Context Protocol para Plane. Dá a um agente de IA ferramentas para ler e gerenciar projetos, itens de trabalho, ciclos, módulos, releases, clientes e muito mais.

Construído sobre FastMCP e o plane-sdk oficial.

28 ferramentas, uma por recurso do Plane, cobrindo 183 operações
Local ou remoto — stdio, HTTP streamable, SSE
Autenticação OAuth ou chave de API

Início rápido

Obtenha uma chave de API do Plane: Workspace Settings → API tokens.

Adicione isto à configuração do seu cliente MCP:

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

uvx não requer etapa de instalação. Requer Python 3.10+.

Para um Plane auto-hospedado, adicione "PLANE_BASE_URL": "https://plane.example.com".

Transportes

stdio — local

Executa como um subprocesso do seu cliente MCP. Configuração como mostrado acima; requer PLANE_API_KEY e PLANE_WORKSPACE_SLUG.

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

HTTP com OAuth — hospedado

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

O fluxo OAuth é tratado na conexão; nenhuma credencial na sua configuração. Para clientes sem suporte nativo a MCP remoto, faça a ponte com mcp-remote:

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

Requer Node.js 22+.

HTTP com token de acesso pessoal — hospedado

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

Cabeçalho	Valor
`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 — obsoleto

https://mcp.plane.so/sse é mantido apenas para compatibilidade reversa. Use um transporte HTTP em vez disso.

Ferramentas

O servidor anuncia 28 ferramentas, uma por recurso. Cada uma recebe um parâmetro action que seleciona a operação:

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

A descrição de cada ferramenta lista suas ações com seus parâmetros obrigatórios e opcionais, então o catálogo é autodocumentado no momento da chamada.

→ Referência completa de ferramentas e ações

Consultando itens de trabalho

Listar, contar e pesquisar aceitam PQL, a linguagem de consulta do 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")

Chame get_pql_reference para a sintaxe completa, operadores e exemplos práticos.

Atualizando a partir das ferramentas por operação

Versões anteriores expunham uma ferramenta por operação de API. Integrações existentes continuam funcionando: 169 desses 177 nomes ainda resolvem para a ferramenta consolidada, então um prompt salvo ou script que chama create_work_item ou list_cycles não precisa de mudança. Eles não são mais anunciados e mantêm os nomes de parâmetros com os quais foram lançados (work_item_id, não workitem_id).

Sete nomes escolhiam entre duas operações com um parâmetro (manage_project_archive(archive=False)), o que um único par ferramenta-ação não consegue reproduzir; chamar um deles informa seu substituto. get_pql_reference está inalterado.

Configuração

Autenticação

Variável	Obrigatória para	Finalidade
`PLANE_API_KEY`	stdio	Chave de API
`PLANE_WORKSPACE_SLUG`	stdio	Workspace de destino
`PLANE_BASE_URL`	opcional	URL da API do Plane (padrão `https://api.plane.so`)

Os transportes remotos carregam credenciais na conexão — o fluxo OAuth ou os cabeçalhos PAT — e não precisam de nenhuma destas.

Auto-hospedando o próprio servidor:

Variável	Finalidade
`PLANE_INTERNAL_BASE_URL`	URL interna para chamadas servidor-a-servidor, preferida em relação a `PLANE_BASE_URL`
`REDIS_HOST` / `REDIS_PORT`	Armazenamento de tokens OAuth; usa fallback em memória
`PLANE_OAUTH_PROVIDER_*`	Credenciais do cliente OAuth e URL base
`MCP_PATH_PREFIX`	Prefixo de caminho para as rotas HTTP, quando montado atrás de um proxy — `/plane` serve `/plane/http/mcp`

URIs de redirecionamento OAuth

Os transportes OAuth validam a URI de redirecionamento de cada cliente contra uma lista de permissões. Clientes comuns (Cursor, VS Code, Claude.ai, conectores ChatGPT, localhost) são permitidos por padrão.

Para integrar um novo cliente sem um release, acrescente padrões:

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

* corresponde a qualquer porta, segmento de caminho ou subdomínio. Mantenha o host fixo e use curinga apenas na porta ou no caminho.

Registro de logs

JSON estruturado. Cada chamada de ferramenta registra seu nome, duração, status e — quando disponível — um ID de usuário opaco e o slug do workspace.

export LOG_USER_INFO=true    # also log the display name (PII); default false

Apenas os transportes OAuth e PAT carregam um nome de exibição; stdio não é afetado.

Desenvolvimento

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

Execute o servidor contra um workspace:

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

Testes, formatação, lint:

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

A suíte roda totalmente offline — cada ação de cada recurso é executada contra um substituto que vincula cada chamada à assinatura genuína do plane-sdk. Veja plane_mcp/tools/README.md.

Testes de integração ao vivo são ignorados a menos que você os aponte para um servidor em execução:

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

Eles gravam dados reais nesse workspace.

Estrutura do repositório

Caminho	Conteúdo
`plane_mcp/__main__.py`	ponto de entrada; escolhe o transporte a partir de `argv[1]`
`plane_mcp/server.py`	uma fábrica por transporte
`plane_mcp/client.py`	resolve credenciais em um cliente `plane-sdk`
`plane_mcp/auth/`	provedor OAuth e autenticação por cabeçalho
`plane_mcp/tools/`	a superfície de ferramentas: um módulo por recurso do Plane
`plane_mcp/toolkit/`	blocos de construção compartilhados para a superfície de ferramentas
`plane_mcp/pql_reference.py`	referência de sintaxe PQL servida aos modelos

Contribuindo

Pull requests são bem-vindos. Por favor, execute pytest e ruff check antes de enviar; novas ferramentas devem vir com os invariantes descritos em plane_mcp/tools/README.md.

Veja CONTRIBUTING.md e CODE_OF_CONDUCT.md.

Migrando do servidor Node.js

@makeplane/plane-mcp-server (Node.js) está obsoleto e sem manutenção. Esta implementação em Python o substitui.

Node.js	Python
`PLANE_API_KEY`	`PLANE_API_KEY`
`PLANE_API_HOST_URL`	`PLANE_BASE_URL`
`PLANE_WORKSPACE_SLUG`	`PLANE_WORKSPACE_SLUG`

Substitua o command e o args pela configuração stdio em Início rápido.

Licença

MIT — veja LICENSE.