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.

Client	One-liner
Claude Code (plugin: MCP + skills + preflight)	/plugin marketplace add omnicoreos/planka-mcp then /plugin install planka@planka-mcp
Claude Code (server only)	claude mcp add --scope user --transport stdio planka --env PLANKA_BASE_URL=https://planka.example.com --env PLANKA_API_KEY=<key> -- npx -y @omnicoreos/planka-mcp
Codex CLI	codex mcp add planka -- npx -y @omnicoreos/planka-mcp (then add the env block, below)
Cursor
VS Code
Any of them, guided	npx @omnicoreos/planka-mcp init --client claude|codex|cursor|vscode|print

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:

   Terminal

   Copy

   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:

   Terminal

   Copy

   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:

   config.json

   Copy

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