Plane

Servidor MCP Plane

Um servidor Model Context Protocol para Plane. Fornece 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 oficial plane-sdk.

• 30 ferramentas, uma por recurso do Plane, cobrindo 207 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: Configurações do Workspace → Tokens de API.

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 conforme 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 30 ferramentas, uma por recurso. Cada uma aceita 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 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 chamando create_work_item ou list_cycles não precisa de alteração. 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 pode reproduzir; chamar um 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 sobre PLANE_BASE_URL
REDIS_URL	Armazenamento de token OAuth como uma URL de conexão (redis:// ou rediss:// para TLS); tem precedência sobre host/porta
REDIS_HOST / REDIS_PORT	Armazenamento de token OAuth; usa fallback para 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 o 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 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=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

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.