Planka MCP Server for Claude

Docker Build & Publish

MCP (Model Context Protocol) server that connects Planka kanban boards to Claude.ai for AI-powered project management.

This server exposes all Planka v2 API operations as MCP tools via the Streamable HTTP transport, making it compatible with Claude.ai custom connectors.

Features

75+ MCP tools covering every Planka API endpoint
Streamable HTTP transport (POST /mcp + GET /mcp SSE) for Claude.ai compatibility
Dual authentication: API key (recommended) or email/password with auto-refresh on 401
Composite tools: board overview, project overview, cross-project card search, "my cards"
Multi-session support: each Claude conversation gets its own MCP session
Docker ready: pre-built image on ghcr.io, multi-stage Dockerfile + docker-compose

Prerequisites

Node.js 20+
A running Planka v2.x instance
A dedicated Planka account for Claude (see below)
A publicly accessible domain for the MCP server (e.g. https://planka-mcp.domain.tld)

Quick Start

1. Create a dedicated Planka account for Claude

We strongly recommend creating a dedicated Planka user account specifically for Claude (e.g. claude@yourdomain.tld), rather than using your personal account. This makes it easy to:

Track exactly which actions Claude performed in the activity log
Revoke Claude's access independently without affecting your own account
Apply specific permissions (admin or member) scoped to Claude's needs

2. Install dependencies

npm install

3. Configure

cp .env.example .env
# Edit .env with your Planka URL and Claude's dedicated account credentials

Authentication options (pick one):

Method	Variables	Notes
API Key (recommended)	`PLANKA_API_KEY`	Never expires. Generate via `planka_create_user_api_key` tool
Email + Password	`PLANKA_EMAIL` + `PLANKA_PASSWORD`	Auto-refreshes JWT on 401

4. Expose the server on a public domain

Claude.ai requires the MCP server to be accessible over HTTPS. You need a public domain pointing to this server, for example:

https://planka-mcp.domain.tld

Configure your reverse proxy (Nginx, Traefik, Caddy…) to forward HTTPS traffic to localhost:3001.

5. Build and run

npm run build
npm start

6. Verify

curl https://planka-mcp.domain.tld/health
# {"status":"ok","planka_url":"http://...","version":"1.0.0"}

7. Add to Claude.ai

Go to Settings > Connectors > Add custom connector
Set the URL to: https://planka-mcp.domain.tld/mcp
⚠️ The URL must include /mcp at the end — Claude.ai will not find the MCP server without it.
Click Add, then Connect and authorize via the OAuth screen
Enable the connector in a conversation via the "+" button > Connectors

Docker

A pre-built image is automatically published to the GitHub Container Registry on every push to main and on every version tag (v*).

ghcr.io/nextheberg/planka-mcp-server-for-claude:latest

Run with docker compose (recommended)

The provided docker-compose.yml pulls the pre-built image by default:

# Pull latest image and start
docker compose up -d

# Check logs
docker compose logs -f planka-mcp

Run with docker directly

docker run -d \
  --name planka-mcp \
  --restart unless-stopped \
  -p 3001:3001 \
  --env-file .env \
  ghcr.io/nextheberg/planka-mcp-server-for-claude:latest

Build locally

To build the image from source instead of pulling it:

# Edit docker-compose.yml: comment out `image:` and uncomment `build:`
docker compose up -d --build

Or directly:

docker build -t planka-mcp-server .

Security

Even though the MCP server is exposed on a public domain, it is effectively inaccessible to anyone except Claude. Here's why:

OAuth required — without completing the OAuth flow (which opens an interactive popup in your browser), no one can obtain a valid token. This flow cannot be automated without human interaction.
Tokens stored in memory only — issued tokens live exclusively in the container's RAM. A container restart invalidates all existing tokens immediately. No database, no persistent storage exposed.
No token = 401 — any direct request to /mcp without a valid Bearer token is rejected immediately.
Tokens are unguessable — format planka-mcp-token-{uuid}, with UUID v4 providing 2¹²² possible values.

The only realistic attack surface is token interception in transit — mitigated entirely by HTTPS/TLS. The OAuth discovery endpoints (/.well-known/*, /oauth/authorize, /oauth/token) are public but grant no access without completing the interactive flow.

In practice: only Claude — after you have clicked "Authorize" — can use this server.

Cost — Using Claude Haiku

Managing Planka tasks (creating cards, updating lists, searching boards…) does not require a powerful model. These are structured, low-complexity operations that work perfectly with Claude Haiku, Anthropic's fastest and most affordable model.

Using Claude Haiku for Planka operations costs a fraction of Claude Sonnet or Opus — making this connector extremely cost-effective for day-to-day project management automation.

Development

npm run dev   # Uses tsx --watch for hot reload

Environment Variables

Variable	Required	Default	Description
`PLANKA_BASE_URL`	Yes	-	Full URL to Planka (e.g. `http://192.168.1.50:3000`)
`PLANKA_API_KEY`	One of	-	API key for authentication
`PLANKA_EMAIL`	One of	-	Email for password auth
`PLANKA_PASSWORD`	One of	-	Password for password auth
`PORT`	No	`3001`	Server listen port
`NODE_TLS_REJECT_UNAUTHORIZED`	No	`true`	Set to `false` for self-signed certs
`PLANKA_REQUEST_TIMEOUT`	No	`30000`	Request timeout in ms
`LOG_LEVEL`	No	`info`	Log level: error, warn, info, debug

Available MCP Tools (75+)

Auth & System

Tool	Description
`planka_get_bootstrap`	Get Planka instance info (version, OIDC, limits)
`planka_get_config`	Get SMTP configuration (admin)
`planka_update_config`	Update SMTP configuration (admin)
`planka_test_smtp`	Test SMTP configuration (admin)

Users

Tool	Description
`planka_list_users`	List all users
`planka_create_user`	Create a new user
`planka_get_user`	Get user details
`planka_update_user`	Update user settings
`planka_delete_user`	Delete a user
`planka_update_user_email`	Change user email
`planka_update_user_password`	Change user password
`planka_update_user_username`	Change username
`planka_create_user_api_key`	Generate API key

Projects

Tool	Description
`planka_list_projects`	List all projects
`planka_create_project`	Create a project
`planka_get_project`	Get project with boards and members
`planka_update_project`	Update project settings
`planka_delete_project`	Delete a project
`planka_add_project_manager`	Add a project manager
`planka_remove_project_manager`	Remove a project manager
`planka_create_base_custom_field_group`	Create base custom field group

Boards

Tool	Description
`planka_create_board`	Create a board
`planka_get_board`	Get board with all content
`planka_update_board`	Update board settings
`planka_delete_board`	Delete a board
`planka_get_board_actions`	Get board activity log
`planka_add_board_member`	Add board member
`planka_update_board_member`	Update member role
`planka_remove_board_member`	Remove board member

Lists

Tool	Description
`planka_create_list`	Create a list
`planka_get_list`	Get list with cards
`planka_update_list`	Update list (name, color, position, move)
`planka_delete_list`	Delete a list
`planka_sort_list`	Sort cards in a list
`planka_move_list_cards`	Move all cards to another list
`planka_clear_list`	Clear all cards from a list

Cards

Tool	Description
`planka_list_cards`	List cards with filters
`planka_create_card`	Create a card
`planka_get_card`	Get card with all details
`planka_update_card`	Update card (move, rename, due date, etc.)
`planka_delete_card`	Delete a card
`planka_duplicate_card`	Duplicate a card
`planka_read_card_notifications`	Mark card notifications read
`planka_get_card_actions`	Get card activity log

Task Lists & Tasks

Tool	Description
`planka_create_task_list`	Create a checklist on a card
`planka_get_task_list`	Get task list with tasks
`planka_update_task_list`	Update task list
`planka_delete_task_list`	Delete task list
`planka_create_task`	Create a task
`planka_update_task`	Update task (complete, assign, rename)
`planka_delete_task`	Delete a task

Labels

Tool	Description
`planka_create_label`	Create a label
`planka_update_label`	Update a label
`planka_delete_label`	Delete a label
`planka_add_label_to_card`	Add label to card
`planka_remove_label_from_card`	Remove label from card

Card Members

Tool	Description
`planka_assign_user_to_card`	Assign user to card
`planka_unassign_user_from_card`	Unassign user from card

Comments

Tool	Description
`planka_list_comments`	List card comments
`planka_create_comment`	Add a comment
`planka_update_comment`	Edit a comment
`planka_delete_comment`	Delete a comment

Attachments

Tool	Description
`planka_add_link_attachment`	Add a link attachment
`planka_update_attachment`	Rename attachment
`planka_delete_attachment`	Delete attachment

Custom Fields

Tool	Description
`planka_update_base_custom_field_group`	Update base field group
`planka_delete_base_custom_field_group`	Delete base field group
`planka_create_custom_field_in_base_group`	Create field in base group
`planka_create_board_custom_field_group`	Create board field group
`planka_create_card_custom_field_group`	Create card field group
`planka_get_custom_field_group`	Get field group
`planka_update_custom_field_group`	Update field group
`planka_delete_custom_field_group`	Delete field group
`planka_create_custom_field_in_group`	Create field in group
`planka_update_custom_field`	Update a custom field
`planka_delete_custom_field`	Delete a custom field
`planka_update_custom_field_value`	Set field value on card
`planka_delete_custom_field_value`	Remove field value from card

Notifications

Tool	Description
`planka_list_notifications`	List all notifications
`planka_get_notification`	Get notification details
`planka_update_notification`	Mark read/unread
`planka_read_all_notifications`	Mark all as read

Notification Services

Tool	Description
`planka_create_board_notification_service`	Create board webhook
`planka_create_user_notification_service`	Create user webhook
`planka_update_notification_service`	Update notification service
`planka_delete_notification_service`	Delete notification service
`planka_test_notification_service`	Test notification service

Webhooks

Tool	Description
`planka_list_webhooks`	List all webhooks
`planka_create_webhook`	Create a webhook
`planka_update_webhook`	Update a webhook
`planka_delete_webhook`	Delete a webhook

Composite Tools

Tool	Description
`planka_get_board_overview`	Full board view: lists + cards + members + labels
`planka_get_project_overview`	Project with boards and card counts per list
`planka_search_cards_in_project`	Search cards across all boards in a project
`planka_get_my_cards`	Get all cards assigned to a user across all projects

Usage Examples (natural language in Claude)

"Show me all my projects"
"Create a new project called 'Website Redesign'"
"What cards are assigned to me?"
"Add a card 'Fix login bug' to the 'To Do' list on the Dev board"
"Move all cards from 'In Progress' to 'Done'"
"Search for cards mentioning 'database' in the Backend project"
"Create a checklist on card X with items: design, implement, test"
"Set the due date for card Y to next Friday"
"Add a comment on card Z: 'This is ready for review'"
"Show me the activity log for the main board"

Architecture

src/
  index.ts                  # Express HTTP server (Streamable HTTP transport)
  server.ts                 # MCP server definition + all 75+ tools
  planka/
    client.ts               # HTTP client (auth, auto-refresh, timeout)
    types.ts                # Full TypeScript type definitions
    api/
      auth.ts               # Access tokens + bootstrap
      projects.ts           # Projects + managers
      boards.ts             # Boards + memberships
      lists.ts              # Lists (CRUD + sort + move + clear)
      cards.ts              # Cards (CRUD + duplicate + notifications)
      task-lists.ts         # Task lists
      tasks.ts              # Tasks
      labels.ts             # Labels + card labels
      card-memberships.ts   # Card member assignments
      comments.ts           # Comments
      attachments.ts        # Attachments (link type)
      custom-fields.ts      # Custom field groups + fields + values
      users.ts              # Users (CRUD + email/password/username/apikey)
      notifications.ts      # Notifications
      notification-services.ts  # Notification services
      webhooks.ts           # Webhooks
      config.ts             # SMTP config

License

GPL-3.0 license