Planka v2

Planka v2.x MCP

Conecte Claude, Cursor, Codex e outros clientes MCP diretamente aos seus quadros Planka v2.x.

Dê aos seus agentes de IA acesso estruturado e seguro a projetos, quadros, cartões, tarefas, comentários, etiquetas e fluxos de trabalho por meio do Model Context Protocol (MCP).

[!IMPORTANT] Desenvolvido especificamente para Planka v2.x. Este MCP não é compatível com Planka v1.x.

Por que usar o Planka MCP?

O Planka oferece uma excelente interface web para usuários humanos. No entanto, agentes de IA precisam de acesso estruturado a projetos, quadros, cartões, tarefas, comentários e fluxos de trabalho.

Este servidor MCP expõe a API do Planka v2 por meio do Model Context Protocol (MCP), permitindo que Claude, Cursor, Codex e outros agentes de IA interajam com o Planka usando linguagem natural.

Versões Suportadas do Planka

Recursos

• Gerenciamento completo de projetos e quadros
• Gerenciamento completo do ciclo de vida de cartões
• Suporte a listas de tarefas e tarefas
• Comentários, etiquetas e atribuições
• Controle de tempo em cartões
• Resumos de projetos e quadros
• Interface de ferramentas nativa do MCP
• Suporte aos principais clientes MCP
• Suporte a Planka auto-hospedado e em nuvem

✓ Created project "Website Redesign"
✓ Created board "Backlog"
✓ Created board "In Progress"
✓ Created board "Done"

Project setup completed successfully.

✓ Created card "Implement authentication"
✓ Created task list
✓ Added 4 tasks

✓ Found 7 overdue cards
✓ Moved cards to "Blocked"
✓ Added explanatory comments
✓ Generated updated project summary

card_manager com action: "get_details" inclui um array attachments com metadados somente leitura: IDs de anexos e cartões, ID do usuário criador, nome, tipo, tipo MIME, tamanho, URL de download ou link e carimbos de data/hora. Ele não baixa nem retorna o conteúdo dos anexos.

Início Rápido

Requisitos

• Uma instância do Planka v2.x em execução
• Uma conta de usuário dedicada do Planka para seu agente de IA
• Node.js 18+ (se executado localmente)

[!IMPORTANT] Após criar a conta do MCP, faça login na interface web do Planka com essa conta e aceite os termos de serviço antes de configurar ou iniciar o servidor MCP. Isso é necessário para toda nova conta.

Configure Seu Cliente MCP

Todo cliente compatível com MCP usa o mesmo comando subjacente — apenas o local do arquivo de configuração (e ocasionalmente o wrapper JSON) difere. Consulte Exemplos de Configuração de Cliente abaixo para sua ferramenta específica.

O bloco de configuração principal é sempre:

{
  "command": "npx",
  "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
    "PLANKA_AGENT_PASSWORD": "your-secure-password",
    "PLANKA_IGNORE_SSL": "true"
  }
}

{
  "command": "node",
  "args": ["/absolute/path/to/planka-v2-mcp/dist/index.js"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
    "PLANKA_AGENT_PASSWORD": "your-secure-password",
    "PLANKA_IGNORE_SSL": "true"
  }
}

[!TIP] Defina PLANKA_IGNORE_SSL como "true" apenas para certificados autoassinados em ambientes confiáveis/locais — deixe-o sem definição em produção.

Verifique a Conexão

Pergunte algo somente leitura ao seu agente primeiro, por exemplo, "Liste meus projetos do Planka." Se você receber uma resposta real, a conexão está configurada corretamente.

Exemplos de Configuração de Cliente

A maioria dos clientes MCP compartilha exatamente o mesmo formato JSON mcpServers — apenas o local do arquivo de configuração difere. Clientes com formato diferente (Codex, Continue, Zed) têm seu próprio bloco abaixo.

{
  "mcpServers": {
    "planka-mcp": {
      "command": "npx",
      "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "true"
      }
    }
  }
}

[mcp_servers.planka-mcp]
command = "npx"
args = ["-y", "@goldpulpy/planka-v2-mcp@latest"]

[mcp_servers.planka-mcp.env]
PLANKA_BASE_URL = "https://your-planka-instance.com"
PLANKA_AGENT_EMAIL = "agent@yourdomain.com"
PLANKA_AGENT_PASSWORD = "your-secure-password"
PLANKA_IGNORE_SSL = "true"

codex mcp add planka-mcp -- npx -y @goldpulpy/planka-v2-mcp@latest

mcpServers:
  - name: planka-mcp
    command: npx
    args:
      - -y
      - "@goldpulpy/planka-v2-mcp@latest"
    env:
      PLANKA_BASE_URL: https://your-planka-instance.com
      PLANKA_AGENT_EMAIL: agent@yourdomain.com
      PLANKA_AGENT_PASSWORD: your-secure-password
      PLANKA_IGNORE_SSL: "true"

{
  "context_servers": {
    "planka-mcp": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "true"
      }
    }
  }
}

npx -y @goldpulpy/planka-v2-mcp@latest

Variáveis de Ambiente

Segurança

• A autenticação é realizada usando uma conta de usuário Planka dedicada.
• As credenciais são fornecidas apenas por meio de variáveis de ambiente.
• O servidor MCP não persiste dados do quadro fora do processo em execução.
• A verificação de certificado SSL está habilitada por padrão.
• PLANKA_IGNORE_SSL=true deve ser usado apenas em ambientes locais confiáveis ou auto-hospedados.

Solução de Problemas

Desenvolvimento

# Install dependencies
npm install

# Configure environment variables
cp .env.example .env

# Start the bundled Planka development instance
npm run planka:up

# Build the project
npm run build

# Run @modelcontextprotocol/inspector
npm run inspector

A instância de desenvolvimento requer Docker Compose e está disponível em http://localhost:3000 (login: admin@example.com / admin). Atualize .env com essa URL e login para uso local. Como com qualquer conta MCP recém-criada, faça login através do navegador e aceite os termos de serviço antes de usar a conta com o servidor MCP. Pare a instância preservando seus dados com npm run planka:down, ou pare-a e exclua seus volumes com npm run planka:clear.

Semear um Quadro de Demonstração

O comando de semeadura exclusivo para desenvolvimento cria um quadro representativo para testes locais e demonstrações. Instale as dependências do projeto e configure .env com uma instância Planka v2 acessível e valores válidos de PLANKA_BASE_URL, PLANKA_AGENT_EMAIL e PLANKA_AGENT_PASSWORD antes de executá-lo.

# Reuse or create the private "Demo Project", then create "Demo Board"
npm run seed

# Seed an existing project
npm run seed -- --project-id <project-id>

# Choose a different board name
npm run seed -- --project-id <project-id> --board-name "My Demo Board"

# Show all options
npm run seed -- --help

O quadro inclui cartões nas listas de fluxo de trabalho padrão, descrições, datas de vencimento relativas, etiquetas Planka usadas como tags, listas de tarefas, tarefas concluídas e incompletas, e comentários. O comando imprime o ID do projeto, ID do quadro, nome do quadro e contagens de recursos quando é bem-sucedido.

O comando de semeadura se recusa a modificar um projeto que já contém um quadro com o nome exato solicitado; use --board-name para escolher outro nome. Se ocorrer um erro após a criação do quadro, o comando relata o estágio com falha e o ID do quadro e deixa o quadro parcialmente preenchido disponível para inspeção. Exclua esse quadro no Planka antes de tentar novamente com o mesmo nome.

A fonte de semeadura e sua saída .seed-dist/ compilada separadamente são exclusivas para desenvolvimento e não são incluídas na compilação do servidor MCP ou no pacote publicado.

Contribuindo

Contribuições são bem-vindas. Veja CONTRIBUTING.md para detalhes.

Agradecimentos

Este projeto é um fork de Navya-Tecnologia/planka-v2-mcp, que se baseia em bradrisse/kanban-mcp. Agradecemos a @virapa e @bradrisse pela base por trás deste código.

Licença

Licenciado sob a Licença MIT. Veja LICENSE para detalhes.

Este projeto foca exclusivamente na interface MCP. Para a configuração do servidor Planka em si, veja a documentação oficial do Planka.