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

* 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:

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.

Links

• GitHub Issues - Report bugs

• Planka - The Kanban board application

• CONTRIBUTING.md - Development & publishing guide

• CHANGELOG.md - Versioned API and tooling updates

• SECURITY.md - Security policy

License

MIT - see LICENSE