planka-mcp

Control a Planka 2.x board from Claude Code through 15 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 ◀──────┘

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.

Related MCP server: Planka MCP Server

Requirements

• Node.js 18 or newer and npm

• A reachable Planka 2.x instance

• A dedicated Planka user that can see the target project and board

• Claude Code installed and available as claude

• A project-manager role only if setup must create a board

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

Install in 5 minutes

Clone the repository and run the guided installer:

git clone https://github.com/omnicoreos/planka-mcp.git
cd planka-mcp
./scripts/setup.sh

Setup asks for the Planka URL, agent email or username, and password. It validates those credentials before writing configuration, lets you select or create a board, and then runs a real create/label/comment/delete smoke test.

It offers two Claude Code configurations:

In both cases, setup stores credentials outside Git in ~/.config/planka-mcp/config.json with mode 0600 and creates the private launcher ~/.local/bin/planka-mcp. A generated team configuration contains no password:

{
  "mcpServers": {
    "planka": {
      "type": "stdio",
      "command": "${HOME}/.local/bin/planka-mcp",
      "args": []
    }
  }
}

The installer is safe to rerun. It updates the planka entry, reuses existing workflow lists and labels, and deletes its temporary smoke-test card.

Verify it works

First, inspect Claude Code's configuration:

claude mcp list
claude mcp get planka

Then fully restart Claude Code. If you chose .mcp.json, open Claude Code in that project and approve the project-scoped server when prompted.

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.

The 15 tools

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

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

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:

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

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.