chmald/planka-mcp repository overview

⁠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"
      ]
    }
  }
}

⁠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⁠