Planka v2

Connect Claude, Cursor, Codex, and other MCP clients directly to your Planka v2.x boards.

Give your AI agents structured, secure access to projects, boards, cards, tasks, comments, labels, and workflows through the Model Context Protocol (MCP).

[!IMPORTANT] Built specifically forPlanka v2.x. This MCP is not compatible with Planka v1.x.

Planka provides an excellent web interface for human users. AI agents, however, need structured access to projects, boards, cards, tasks, comments, and workflows.

This MCP server exposes the Planka v2 API through the Model Context Protocol (MCP), allowing Claude, Cursor, Codex, and other AI agents to interact with Planka using natural language.

- Full project and board management
- Complete card lifecycle management
- Task Lists and tasks support
- Comments, labels, and assignments
- Card time tracking
- Project and board summaries
- MCP-native tool interface
- Support for major MCP clients
- Self-hosted and cloud Planka support

Create a project called "Website Redesign" with boards "Backlog", "In Progress", and "Done".

✓ Created project "Website Redesign" ✓ Created board "Backlog" ✓ Created board "In Progress" ✓ Created board "Done" Project setup completed successfully.

Create a card "Implement authentication" in the Backlog board with tasks:

- Design login flow
- Implement JWT authentication
- Add password reset
- Write tests

✓ Created card "Implement authentication" ✓ Created task list ✓ Added 4 tasks

Find all overdue cards assigned to me, move them to "Blocked", add a comment explaining why, and generate a project summary.

✓ Found 7 overdue cards ✓ Moved cards to "Blocked" ✓ Added explanatory comments ✓ Generated updated project summary

- A running Planka v2.x instance
- A dedicated Planka user account for your AI agent
- Node.js 18+ (if running locally)

[!IMPORTANT] After creating the MCP account, log in to the Planka web interface with that account and accept the terms of service before configuring or starting the MCP server. This is required for every new account.

Every MCP-compatible client uses the same underlying command - only the config file location (and occasionally the JSON wrapper) differs. SeeClient Configuration Examplesbelow for your specific tool.

{ "command": "npx", "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"], "env": { "PLANKA_BASE_URL": "https://your-planka-instance.com", "PLANKA_AGENT_EMAIL": "agent@yourdomain.com", "PLANKA_AGENT_PASSWORD": "your-secure-password", "PLANKA_IGNORE_SSL": "true" } }

{ "command": "node", "args": ["/absolute/path/to/planka-v2-mcp/dist/index.js"], "env": { "PLANKA_BASE_URL": "https://your-planka-instance.com", "PLANKA_AGENT_EMAIL": "agent@yourdomain.com", "PLANKA_AGENT_PASSWORD": "your-secure-password", "PLANKA_IGNORE_SSL": "true" } }

Useful when you're contributing to the server itself or need a pinned, offline build.

[!TIP] SetPLANKA_IGNORE_SSLto"true"only for self-signed certs in trusted/local environments - leave it unset in production.

Ask your agent something read-only first, e.g."List my Planka projects."If you get a real response back, you're wired up correctly.

Most MCP clients share the exact samemcpServersJSON shape - only the config file location differs. Clients with a different format (Codex, Continue, Zed) get their own block below.

{ "mcpServers": { "planka-mcp": { "command": "npx", "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"], "env": { "PLANKA_BASE_URL": "https://your-planka-instance.com", "PLANKA_AGENT_EMAIL": "agent@yourdomain.com", "PLANKA_AGENT_PASSWORD": "your-secure-password", "PLANKA_IGNORE_SSL": "true" } } } }

Drop this block into the relevant config file:

[!NOTE] Claude Code also supports adding the server via a one-liner instead of hand-editing JSON:

claude mcp add planka-mcp \ --env PLANKA_BASE_URL=https://your-planka-instance.com \ --env PLANKA_AGENT_EMAIL=agent@yourdomain.com \ --env PLANKA_AGENT_PASSWORD=your-secure-password \ --env PLANKA_IGNORE_SSL=true \ -- npx -y @goldpulpy/planka-v2-mcp@latest

[mcp_servers.planka-mcp] command = "npx" args = ["-y", "@goldpulpy/planka-v2-mcp@latest"] [mcp_servers.planka-mcp.env] PLANKA_BASE_URL = "https://your-planka-instance.com" PLANKA_AGENT_EMAIL = "agent@yourdomain.com" PLANKA_AGENT_PASSWORD = "your-secure-password" PLANKA_IGNORE_SSL = "true"

codex mcp add planka-mcp -- npx -y @goldpulpy/planka-v2-mcp@latest

then set thePLANKA_variables in the generated[mcp_servers.planka-mcp.env]block.

mcpServers: - name: planka-mcp command: npx args: - -y - "@goldpulpy/planka-v2-mcp@latest" env: PLANKA_BASE_URL: https://your-planka-instance.com PLANKA_AGENT_EMAIL: agent@yourdomain.com PLANKA_AGENT_PASSWORD: your-secure-password PLANKA_IGNORE_SSL: "true"

{ "context_servers": { "planka-mcp": { "source": "custom", "command": "npx", "args": ["-y", "@goldpulpy/planka-v2-mcp@latest"], "env": { "PLANKA_BASE_URL": "https://your-planka-instance.com", "PLANKA_AGENT_EMAIL": "agent@yourdomain.com", "PLANKA_AGENT_PASSWORD": "your-secure-password", "PLANKA_IGNORE_SSL": "true" } } } }

with the fourPLANKA_environment variables set as shown above.

- Authentication is performed using a dedicated Planka user account.
- Credentials are supplied through environment variables only.
- The MCP server does not persist board data outside the running process.
- SSL certificate verification is enabled by default.
- PLANKA_IGNORE_SSL=trueshould only be used in trusted local or self-hosted environments.

- ConfirmPLANKA_BASE_URLhas no trailing slash and is reachable from the machine running the MCP server (not just your browser).
- Check that the agent user can log in with those exact credentials through Planka's normal web UI and has accepted the terms of service.

- If your instance uses a self-signed certificate, set"PLANKA_IGNORE_SSL": "true". Avoid this in production - prefer a valid certificate instead.

- Make sure the card type is"project"(the default). Cards created as"story"type don't expose Task Lists in the same way.

# Install dependencies npm install # Configure environment variables cp .env.example .env # Start the bundled Planka development instance npm run planka:up # Build the project npm run build # Run @modelcontextprotocol/inspector npm run inspector

The development-only seed command creates a representative board for local testing and demonstrations. Install the project dependencies and configure.envwith a reachable Planka v2 instance and validPLANKA_BASE_URL,PLANKA_AGENT_EMAIL, andPLANKA_AGENT_PASSWORDvalues before running it.

# Reuse or create the private "Demo Project", then create "Demo Board" npm run seed # Seed an existing project npm run seed -- --project-id <project-id> # Choose a different board name npm run seed -- --project-id <project-id> --board-name "My Demo Board" # Show all options npm run seed -- --help

The board includes cards across the default workflow lists, descriptions, relative due dates, Planka labels used as tags, task lists, completed and incomplete tasks, and comments. The command prints the project ID, board ID, board name, and resource counts when it succeeds.

The seed command refuses to modify a project that already contains a board with the exact requested name; use--board-nameto choose another name. If an error occurs after board creation, the command reports the failed stage and board ID and leaves the partially populated board available for inspection. Delete that board in Planka before retrying with the same name.

The seed source and its separately compiled.seed-dist/output are development-only and are not included in the MCP server build or published package.

Contributions are welcome. SeeCONTRIBUTING.mdfor details.

This project is forked fromNavya-Tecnologia/planka-v2-mcp, which builds onbradrisse/kanban-mcp. Thanks to@virapaand@bradrissefor the foundation behind this codebase.

Licensed under the MIT License. SeeLICENSEfor details.

This project focuses exclusively on the MCP interface. For Planka server setup itself, see theofficial Planka documentation.

An MCP extension for the Claude Desktop application that enables automation and integration.