MMCPMarkets
CP

chmald/planka-mcp

Developer tools
6 stars 3 forks Quality 72 Trend 14MIT
Repository Install

MCP server for Planka - enables AI assistants to interact with Planka kanban boards via Model Context Protocol. Supports multi-client connections via SSE.

Overview

An MCP server that enables AI assistants (Claude, VS Code Copilot, etc.) to interact with Planka - a real-time Kanban board application. - or - running and accessible - with appropriate permissions Use host.docker.internal instead of localhost when running Docker. * Authentication is required. Provide either PLANKA_API_KEY, or both PLANKA_USERNAME and PLANKA_PASSWORD. - Set PLANKA_API_KEY. - Set PLANKA_USERNAME and PLANKA_PASSWORD. - If both are set, the server uses PLANKA_API_KEY. - Retries apply to transient failures (408, 429, 5xx) and network request errors. - Delay uses exponential backoff: PLANKA_HTTP_RETRY_BASE_DELAY_MS * 2^attempt. - PLANKA_HTTP_MAX_RETRIES controls additional attempts after the initial request. By default, are enabled for essential Kanban operations: Each tool uses an action parameter. Example: { "action": "list" } or { "action": "get", "id": "123" }

README

Planka MCP Server

An MCP server that enables AI assistants (Claude, VS Code Copilot, etc.) to interact with Planka - a real-time Kanban board application.

Quick Start

Prerequisites

  • Node.js 18+ or Docker
  • Planka instance running and accessible
  • Planka user account with appropriate permissions

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["@chmald/planka-mcp"],
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3000",
        "PLANKA_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "planka": {
      "type": "stdio",
      "command": "npx",
      "args": ["@chmald/planka-mcp"],
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3000",
        "PLANKA_API_KEY": "your-api-key"
      }
    }
  }
}

Docker

{
  "mcpServers": {
    "planka": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "PLANKA_BASE_URL=http://host.docker.internal:3000",
        "-e", "PLANKA_API_KEY=your-api-key",
        "chmald/planka-mcp:latest"
      ]
    }
  }
}

Note: Use host.docker.internal instead of localhost when running Docker.

Configuration

Environment Variables

Variable Required Default Description
PLANKA_BASE_URL Yes http://localhost:3000 Your Planka instance URL
PLANKA_API_KEY No* - Planka API key sent as X-Api-Key
PLANKA_USERNAME No* - Planka username or email
PLANKA_PASSWORD No* - Planka password
MCP_TRANSPORT No stdio MCP transport mode: stdio or sse
MCP_PORT No 3001 HTTP port used when MCP_TRANSPORT=sse
PLANKA_HTTP_MAX_RETRIES No 2 Max retry attempts for transient HTTP/network failures per request
PLANKA_HTTP_RETRY_BASE_DELAY_MS No 250 Base retry delay in milliseconds (exponential backoff)
ENABLE_ALL_TOOLS No false Enable all 27 tools
ENABLE_ADMIN_TOOLS No false Enable admin tools
ENABLE_OPTIONAL_TOOLS No false Enable optional tools

* Authentication is required. Provide either PLANKA_API_KEY, or both PLANKA_USERNAME and PLANKA_PASSWORD.

Authentication Modes

  • API key (recommended): Set PLANKA_API_KEY.
  • Username/password: Set PLANKA_USERNAME and PLANKA_PASSWORD.
  • If both are set, the server uses PLANKA_API_KEY.

Retry Behavior

  • Retries apply to transient failures (408, 429, 5xx) and network request errors.
  • Delay uses exponential backoff: PLANKA_HTTP_RETRY_BASE_DELAY_MS * 2^attempt.
  • PLANKA_HTTP_MAX_RETRIES controls additional attempts after the initial request.

Tool Categories

By default, 10 core tools are enabled for essential Kanban operations:

Category Tools Description
Core 10 Auth, projects, boards, lists, cards, tasks, comments, labels (always enabled)
Optional 13 Attachments, custom fields, notifications, etc.
Admin 4 User management, webhooks, config

Enable more tools:

"env": {
  "ENABLE_ALL_TOOLS": "true"
}

Available Tools

Each tool uses an action parameter. Example: { "action": "list" } or { "action": "get", "id": "123" }

Multi-Client Mode (SSE)

For team deployments where multiple clients share one server:

docker run -d \
  --name planka-mcp \
  -p 3001:3001 \
  -e MCP_TRANSPORT=sse \
  -e PLANKA_BASE_URL=http://your-planka-server:3000 \
  -e PLANKA_API_KEY=your-api-key \
  chmald/planka-mcp:latest

Connect clients to http://localhost:3001/sse.

Troubleshooting

“Authentication failed”

  • Verify your API key (or username/password) is correct
  • Check that PLANKA_BASE_URL is accessible

“Connection refused” with Docker

  • Use host.docker.internal instead of localhost
  • Ensure Planka is running

npx fails

  • Ensure Node.js 18+ is installed: node --version
  • Try: npm cache clean --force

Debug logs

npx @chmald/planka-mcp 2>&1 | tee debug.log

Upgrade Notes

Check CHANGELOG.md for full version-by-version details.

Upgrading to 2.0.3

  • The auth tool moved from optional tools to core tools and is now always available.
  • API key authentication is now supported with PLANKA_API_KEY (X-Api-Key).
  • If both API key and username/password are configured, PLANKA_API_KEY is used.

License

MIT - see LICENSE

View the full README on GitHub

Install

npx @chmald/planka-mcp
New to MCP? Start with the mcpskill.org guide →

Configuration

{ "mcpServers": { "planka": { "command": "npx", "args": ["@chmald/planka-mcp"], "env": { "PLANKA_BASE_URL": "http://localhost:3000", "PLANKA_API_KEY": "your-api-key" } } } }