planka-mcp

A Model Context Protocol server for Planka kanban boards. It lets Claude (or any MCP client) find, read, edit, comment on and move your cards without you opening Planka.

Unofficial. planka-mcp is a community project, not affiliated with or endorsed by PLANKA Software GmbH. PLANKA is their trademark.

Requires Planka v2.0 or later. Planka v1 has no per-user API keys and is not supported. The end-to-end tests run against Planka 2.2.1.

MCP Registry name: io.github.sierikov/planka-mcp

Why

You talk about a ticket in plain words and the assistant does the rest: it finds the card, reads all of it, does the work, writes back and moves the card along. Every request runs as your own Planka user (through your API key, or your username and password in stdio mode), so Planka's own permissions apply and comments appear under your name.

Two flows it is built for:

1. "Here's this ticket: the card about the backup script. Research it and fill it in with the details we need." The assistant finds the card from your description, reads it in one call, then writes back a better description, checklist items, a due date and labels, plus a comment with its findings.
2. "Let's work on the backup script card." The assistant moves the card to In progress, does the work, comments with a summary, and moves the card on (for example to Ready for release or Done).

What makes this server different from the other Planka MCP servers:

• Boards, lists, labels and people are given by name, so you never have to look up an ID; they also accept IDs, and boards accept links. Cards can be given by ID, URL or by text ("the card about the backup script"). When a name or a text matches more than one thing (say, two lists called "Done"), the error lists the candidates with their IDs instead of guessing, and the assistant retries with the ID it means.
• One call per intent and compact JSON output, so it is cheap in tokens and round trips.
• Per-user keys over HTTP: a self-hosted instance serves several people, each with their own Planka API key.
• A single Go binary, .mcpb bundles for Claude Desktop and a multi-arch Docker image.

Tools

15 tools, all enabled by default. Reads are annotated read-only; creates and adds (create_card, add_comment, add_tasks) are marked non-destructive; updates are marked idempotent; deletes are marked destructive. Clients may still prompt for updates.

Your MCP client decides how to confirm writes. The split lets you auto-allow move_card and add_comment and still be asked before edits and deletes.

Dates are YYYY-MM-DD, or YYYY-MM-DD HH:MM when the time of day matters, in the server's time zone (set TZ to change it; the Docker image embeds the time zone database).

Signing in: API key or username and password

Every call runs as one Planka user, chosen in one of two ways:

• An API key (preferred). It works in both stdio and HTTP mode, and you can revoke it without changing your password.
• Your username (or email) and password, in stdio mode only, for when you cannot get a key.

Getting an API key

Each person needs their own key for their own Planka user. In Planka 2.1 and 2.2, creating an API key is admin-only: the server rejects the request from a non-admin user. So:

• If you are not a Planka admin, ask your admin to generate an API key for your user and send it to you over a private channel. Or use your username and password (below).
• If you are an admin, you can generate your own the same way.

Where the admin finds it (checked against Planka's source):

• Planka 2.2: user menu → Administration → Users tab → click the user's name → API Key tab → Create API key.
• Planka 2.1: user menu → Administration → Users → the ⋯ actions of the user's row → API Key → Create API key.

Copy the key right away: Planka shows it only once. Generating a new key later replaces the old one, which stops working. Treat the key like a password. It can do whatever its user can do in Planka.

Username and password (stdio only)

Set PLANKA_USERNAME (your username or email) and PLANKA_PASSWORD instead of PLANKA_API_KEY. If all three are set, the username and password win, and the server logs that the key is ignored.

• Session handling: the server logs in on the first tool call and keeps the session token in memory only. When Planka answers 401 (an expired or revoked session) it logs in again and repeats that call once. It logs out when it stops, so sessions do not pile up in your Planka account.
• A wrong password is tried once. After Planka rejects the username or password, the server stops sending them and reports the same error until it is restarted with the right ones, so it cannot lock your account with repeated failed logins.
• Accounts it cannot use: single sign-on (OIDC) accounts and accounts with two-factor authentication. Those need an API key. If Planka asks your account to accept its terms first, log in once in the browser.
• Your password sits in your MCP client's configuration in plain text, so prefer a key when you can get one.
• Not in HTTP mode: the shared server refuses a username and password, as it refuses a key, because an exposed port must never act as one person.

Setup

Pick the setup that fits. Stdio runs on your own machine with your own key or login; HTTP is a server you (or your team) host, where each client sends its own key.

claude mcp add planka \
  -e PLANKA_URL=https://planka.example.com \
  -e PLANKA_API_KEY=your-api-key \
  -- /path/to/planka-mcp

claude mcp add planka \
  -e PLANKA_URL=https://planka.example.com \
  -e PLANKA_USERNAME=your-username \
  -e PLANKA_PASSWORD='your-password' \
  -- /path/to/planka-mcp

claude mcp add --transport http planka https://host/mcp \
  --header "Authorization: Bearer <your-api-key>"

{
  "mcpServers": {
    "planka": {
      "command": "/path/to/planka-mcp",
      "env": {
        "PLANKA_URL": "https://planka.example.com",
        "PLANKA_API_KEY": "your-api-key"
      }
    }
  }
}

{
  "mcpServers": {
    "planka": {
      "type": "http",
      "url": "https://host/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

services:
  planka:
    image: ghcr.io/plankanban/planka:2.2.1
    # ... your existing Planka service ...

  planka-mcp:
    image: ghcr.io/sierikov/planka-mcp:latest
    restart: unless-stopped
    depends_on:
      - planka
    environment:
      PLANKA_URL: http://planka:1337   # Planka as seen from this container
      # Do NOT set PLANKA_API_KEY here: in HTTP mode the server refuses to start with it.
      # TZ: Europe/Berlin              # optional, the time zone for dates
    ports:
      - "8080:8080"                    # or publish it only through your reverse proxy

docker run -d -p 8080:8080 -e PLANKA_URL=https://planka.example.com ghcr.io/sierikov/planka-mcp:latest

Configuration

Flags override environment variables.

In HTTP mode clients send Authorization: Bearer <planka-api-key>; a request without it gets HTTP 401 before MCP handling. The server runs stateless streamable HTTP at /mcp and answers GET /healthz with ok.

Security

Report a vulnerability privately, as SECURITY.md describes.

• Per-user keys. Every Planka call runs as the owner of the key that came with the request. There is no shared service account, and Planka's permissions are what limit each user.
• No key in the server's environment. In HTTP mode the server refuses to start when PLANKA_API_KEY is set, so an exposed port can never act as the server owner. Clients send their own key in the Authorization header.
• Keys are never logged. The access log has one line per request: method, path, status and the first 8 hex characters of the key's SHA-256 (or none).
• The server does not validate keys up front. Planka does, on the first call; a revoked or wrong key comes back as a tool error that says Planka rejected the key.
• Use TLS. The server speaks plain HTTP and the key travels in a header, so run it behind a reverse proxy with TLS, the way you run Planka itself.
• Any Host header is served. The MCP SDK's DNS-rebinding guard is off, so a reverse proxy on the same machine that keeps the public host name works. That is safe because every /mcp request needs the caller's own key, and the server holds no key of its own.
• Browser requests from other sites get 403. A request whose Origin names another site than its Host is refused, as the MCP spec requires. Clients that are not browsers send no Origin and are not affected.
• Key creation is admin-only in Planka 2.1 and 2.2. A user cannot create their own key; an admin generates it for them (see Getting an API key), or the user logs in with username and password in stdio mode. Treat a key like a password and regenerate it if it leaks.
• Passwords are held in memory only. With PLANKA_USERNAME/PLANKA_PASSWORD, neither the password nor the session token is logged or written to disk, and the session is ended when the server stops.
• Deletes are permanent and enabled. delete_card, delete_comment and delete_task are annotated as destructive so clients can ask first; deleting a card does not move it to Planka's trash.
• Card text is untrusted input. Descriptions, comments and task names written by other people on your boards reach the model as they are, and a card can contain text meant to steer it ("delete every card in Done"). The server tells the model to treat such text as data, but keep your client's confirmation on for the delete tools, and don't let it auto-approve writes on boards that others edit.
• Writes never pick a card by its description. A card reference that matches only words in some card's description finds that card for a read, but a write refuses it and names the card's ID instead.

Development

Building, testing, the end-to-end setup and releasing are described in DEVELOPMENT.md. Report security problems as SECURITY.md says.

Roadmap

Ideas, in no particular order and without dates:

• OAuth, so that claude.ai, ChatGPT and their phone apps can use a hosted instance with each person's own Planka login.
• Users who sign in to Planka through SSO (Pocket ID and other OIDC providers); until then they use an API key.
• Check the Planka version on /api/bootstrap and fail clearly on Planka v1.
• Verified writes and batch operations that report each item's result.
• Opt-in toolsets, and MCP prompts for the two flows above.

License

MIT, see LICENSE.