planka-mcp

Control a Planka 2.x board from Claude Code through 41 MCP tools. Writes are re-read and verified, so a reported success matches the board. An optional workflow turns that board into durable memory for agent work.

Leer en español

You talk to Claude Code
          │
          ▼
  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
          │                                  │
          └──── reads the result back ◀──────┘

[!WARNING] The old @gogogadgetbytes/planka-mcp package can report success while doing nothing on Planka 2.x. Read the five silent-failure gotchas before replacing an existing installation.

New to MCP? Read this first

MCP is a standard that lets Claude Code call tools provided by another program. This repository runs a small local program that translates those tool calls into Planka API requests. It needs Planka credentials because it acts as a dedicated Planka user, not as Claude itself. The credentials stay on your machine and are never written into the project-level .mcp.json file. Claude Code loads MCP servers when a session starts, so restart it after setup or configuration changes.

Requirements

• Node.js 18 or newer and npx
• A reachable Planka 2.x instance
• A dedicated Planka user that can see the target project and board
• One MCP client: Claude Code, Codex CLI, Cursor or VS Code
• A project-manager role only if setup must create a board

Linux and macOS are supported. No Bun runtime is required.

Install

One command per client. All of them run the published package with npx, so there is nothing to clone and nothing to build.

The Cursor and VS Code links carry a placeholder key, never a real one: a deeplink ends up in browser history. Both clients ask for the credential themselves — VS Code through a promptString input, so the committed .vscode/mcp.json holds no secret.

planka-mcp init

npx @omnicoreos/planka-mcp init --client claude     # claude mcp add, user scope
npx @omnicoreos/planka-mcp init --client codex      # appends to ~/.codex/config.toml
npx @omnicoreos/planka-mcp init --client cursor     # merges ~/.cursor/mcp.json (0600) + prints the deeplink
npx @omnicoreos/planka-mcp init --client vscode     # writes .vscode/mcp.json with a secret prompt
npx @omnicoreos/planka-mcp init --client print      # prints every snippet, writes nothing

With a terminal attached it asks for what it needs; --base-url, --api-key, --board, --email and --password make it non-interactive. Before writing anything it runs one authenticated GET /api/users/me, which is what catches a base URL pointing at the SPA instead of the API, or a credential that never worked. --dry-run prints the exact change and touches nothing.

Every emitter merges: an existing planka entry is reported and left alone, and the other servers in the same file are preserved. Files written into your home directory get mode 0600.

./scripts/setup.sh is an alias for init --client claude. The older guided installer — the one that also picks or creates a board and runs the full create/label/comment/delete smoke test — is still node scripts/setup.mjs.

The Claude Code plugin

The plugin installs the MCP server, the two workflow skills, and a SessionStart preflight that catches a missing credential or an http:// base URL before the first tool call:

/plugin marketplace add omnicoreos/planka-mcp
/plugin install planka@planka-mcp

Claude Code asks for the base URL and the API key when the plugin is enabled and stores the key in the OS keychain, not in settings.json. Codex reads the same repository through .codex-plugin/plugin.json and .agents/plugins/marketplace.json.

Plugins cannot ship permission rules, which is the one thing that does not travel: use PLANKA_READ_ONLY and PLANKA_DISABLED_TOOLS (below) instead of a client-side deny list — they work in every runtime and cost no context.

Codex env block

codex mcp add does not take credentials, so add them to ~/.codex/config.toml (or let init --client codex do it):

[mcp_servers.planka]
command = "npx"
args = ["-y", "@omnicoreos/planka-mcp"]
env = { PLANKA_BASE_URL = "https://planka.example.com", PLANKA_API_KEY = "<key>" }

Verify it works

First, inspect Claude Code's configuration:

claude mcp list
claude mcp get planka

Then fully restart Claude Code — MCP servers are loaded when a session starts. If you configured the server in a project's .mcp.json, open Claude Code in that project and approve the project-scoped server when prompted. If you installed the plugin, /plugin shows it, and its Errors tab shows a server that failed to start.

Ask Claude Code:

Show me my Planka projects and boards. In the Pending list, create a card named
"MCP is working" with the description "Created from Claude Code", then read it back.

If Claude cannot see the tools, restart first and then follow Troubleshooting.

Authentication

Two ways to authenticate, and they are mutually exclusive: setting both is a configuration error, because Planka reads Authorization first and silently ignores x-api-key when both arrive.

Recipe: a scoped agent user with an API key

Four steps, run by a Planka admin. The result is a user that can only ever see the boards you name — enforced by Planka itself, not by this server.

1. Create the user with the lowest global role. In the Planka UI: Administration → Users → Add user, role boardUser. A boardUser cannot create projects and cannot grant itself memberships.

2. Give it membership on the boards it should work on, and only those:

   curl -X POST "$PLANKA_URL/api/boards/<BOARD_ID>/board-memberships" \
     -H "Authorization: Bearer $ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"userId":"<USER_ID>","role":"editor"}'
   

   Use "role":"viewer" for an agent that should read and comment but never create or move cards. GET /api/projects then returns only the projects derived from these memberships; every other board answers 404.

3. Issue the API key (admin-only endpoint). The key is shown once, in included.apiKey; Planka stores only its hash and prefix:

   curl -X POST "$PLANKA_URL/api/users/<USER_ID>/api-key" \
     -H "Authorization: Bearer $ADMIN_TOKEN"
   

4. Configure the server with the key and nothing else. Remove PLANKA_AGENT_EMAIL and PLANKA_AGENT_PASSWORD:

   {
     "mcpServers": {
       "planka": {
         "command": "npx",
         "args": ["-y", "@omnicoreos/planka-mcp"],
         "env": {
           "PLANKA_BASE_URL": "https://planka.example.com",
           "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef"
         }
       }
     }
   }
   

Rotating a key is step 3 again: issuing a new one invalidates the old.

Scoping the server

An API key inherits its user's permissions — it carries no scopes of its own. Scoping therefore happens in three layers, and each covers something the others cannot.

Layer 1 · PLANKA          the only layer an agent cannot talk its way around
  boardUser + board memberships + the API key above
  ⇒ everything outside the allowed boards is 404/403 at the API

Layer 2 · THIS SERVER     ergonomics, and defence against the agent itself
  the environment variables below; they travel with the package,
  so Claude Code, Codex and Cursor all get the same rules

Layer 3 · THE CLIENT      survives a downgrade of this package
  .claude/settings.json deny/ask rules, Codex enabled_tools/disabled_tools

Layer 1 has real enforcement but cannot express "do not call planka_get_board, it costs forty times more context". Layer 2 can, and reaches every runtime. Layer 3 stays true even if this package is pinned back to an older version.

Layer 2: the environment variables

The server ships with no board vocabulary of its own. Column names and "ready" labels are yours, in your language: the last two variables are how a deployment tells the summary what its board looks like. A hint that matches nothing comes back in warnings, never as an empty answer.

"PLANKA_SUMMARY_DECISION_LISTS": "decision,probalo,miralo",
"PLANKA_SUMMARY_HIGHLIGHT_LABEL": "decidido"

Allowlists are by id, never by name. Any board editor can rename a board, so a name-based allowlist is bypassed with one edit. Planka ids are stable.

Two notes on what these are and are not:

• PLANKA_READ_ONLY hides tools; it does not make the account read-only. Pair it with "role":"viewer" in step 2 above if that is what you actually need.
• PLANKA_PROTECTED_LIST_IDS is a guard-rail, not a permission: Planka has no per-list rights. It is the right tool for "do not move cards to Merged on your own", and the wrong one for anything security-critical.

Example — an agent that reads one board and comments, and nothing else:

"env": {
  "PLANKA_BASE_URL": "https://planka.example.com",
  "PLANKA_API_KEY": "abcd1234_0123456789abcdef0123456789abcdef",
  "PLANKA_DEFAULT_BOARD_ID": "1234567890123456789",
  "PLANKA_ALLOWED_BOARD_IDS": "1234567890123456789",
  "PLANKA_DISABLED_TOOLS": "get_board",
  "PLANKA_PROTECTED_LIST_IDS": "9876543210987654321"
}

The 41 tools

IDs are strings. Start with planka_get_structure, then use IDs returned by Planka; do not guess them.

The reads follow one principle: a small digest by default, the detail through parameters. planka_board_summary opens a session in one call; planka_find_cards with a listId reads a whole column in ONE request through GET /api/lists/:id, so total is the real size of the column and the answer carries truncated: false; the same tool without a listId searches the board. Measured on the reference board of 185 cards, the deprecated planka_get_board went from 56,112 to 17,215 characters and planka_get_structure (withLists: false) from 696 to 203, while a 159-card column went from five requests to two. Every read reports total, returned and hasMore, so a clipped answer never looks complete, and every board-derived read carries excludesArchived: true because Planka keeps archive and trash out of the board read.

Every input field and a complete payload for every tool are in Tools reference.

What the client learns on connect

The initialize handshake returns a short set of server instructions — how to open a session, where IDs come from, why every comment on a card matters, and that Planka answers 404 where it means 403. Claude Code puts them in the session system prompt and Codex CLI reads them alongside the tool list, so the shared guidance is stated once instead of repeated in 41 tool descriptions. Every tool also publishes a display title and all four MCP behavioural hints explicitly, rather than inheriting the spec's pessimistic defaults, plus the two _meta keys Claude Code acts on: a forced confirmation prompt on the tools that delete data, and a raised output ceiling on planka_view_attachment. Details in Server instructions and annotations.

Resources and prompts

Two more surfaces, and both cost nothing until something asks for them, which is why the long-form guidance lives here instead of in the instructions everyone pays for on every session. Claude Code reads both; Cursor reads both; Codex supports neither, so nothing here is load-bearing.

Resources serve the guides that ship inside the package. In Claude Code they are @-mentioned, in Cursor they come from the resource picker:

Prompts are three ways to start, surfaced by Claude Code as /mcp__planka__<name>:

Optional agent workflow

The MCP server works on its own. The optional method solves a different problem: preserving why work exists, what changed, and what remains true between agent sessions.

Adopt it in layers:

1. Use only the MCP tools.
2. Add the board states, card template, and human handshakes.
3. Add one worktree per card with a director coordinating workers.

Start with A board that survives the session. The board template, copyable Claude Code skills, and optional worktree helper are independent pieces.

Troubleshooting

• Symptoms, causes, and exact fixes
• Why Planka 2.x breaks older MCP servers silently
• Complete tool payloads

When reporting a bug, include the Planka version, Node version, the tool name, and the error text. Never paste credentials or access tokens.

Credits and license

This is an MIT-licensed fork of gogogadgetbytes/planka-mcp, not an original-from-scratch implementation. See CREDITS.md for the upstream attribution, maintained fixes, and unanswered pull requests.

See LICENSE for the original and current contributor notices.

Development

npm ci
npm run build
npm test

The real smoke test is opt-in because it mutates a writable board and then cleans up after itself. It drives all 41 tools over stdio and cross-checks every write against the raw Planka API — over 90 named checks:

export PLANKA_BASE_URL="https://planka.example.com"
export PLANKA_AGENT_EMAIL="agent@example.com"
export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
npm run test:smoke

npm run test:smoke builds first, so it cannot test a stale dist/. Four optional variables tune it:

See CONTRIBUTING.md before opening a change. Release identity is centralized in project.identity.json; update it and run npm run sync:identity before publishing under your own namespace.