@chmald/planka-mcp

v2.0.4

Published

12 days ago

MCP server for Planka - Real-Time Collaborative Kanban Board

0High
0Medium
0Low

chmald

mcp planka kanban model-context-protocol

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

| Tool | Actions | |------|---------| | auth | login, logout, acceptTerms, oidcExchange, revokePending, getTerms | | bootstrap | get - Get app data, user info, projects | | projects | list, get, create, update, delete | | boards | get, create, update, delete | | lists | get, create, update, delete | | cards | list, get, create, update, delete | | comments | list, create | | tasks | getList, createList, create, update | | labels | create, update, delete, addToCard, removeFromCard | | cardMembers | add, remove |

| Tool | Actions | |------|---------| | config | get, update, testSmtp | | users | list, create, update, delete, updateEmail, updatePassword, etc. | | webhooks | list, create, update, delete | | projectManagers | add, remove |

| Tool | Actions | |------|---------| | attachments | create, update, delete | | boardMembers | add, update, remove | | customFields | createBaseGroup, createField, setValue, etc. | | notifications | list, get, markRead, markAllRead, markCardRead, createUserService, createBoardService, updateService, deleteService, testService | | actions | boardActions, cardActions | | cardExtras | duplicate | | commentExtras | update, delete | | listExtras | clear, moveCards, sort | | taskExtras | updateList, deleteList, deleteTask | | labelExtras | update, delete, removeFromCard | | cardMemberExtras | remove | | backgroundImages | upload, delete | | userInfo | get |

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