Planka v2.x MCP

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 for Planka v2.x. This MCP is not compatible with Planka v1.x.

Why Planka MCP?

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.

Supported Planka Versions

Features

• 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

Example Conversations

Project Setup

User

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

Assistant

✓ Created project "Website Redesign"
✓ Created board "Backlog"
✓ Created board "In Progress"
✓ Created board "Done"

Project setup completed successfully.

Task Creation

User

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

>

> - Design login flow

> - Implement JWT authentication

> - Add password reset

> - Write tests

Assistant

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

Workflow Automation

User

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

Assistant

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

Available Tools

Quick Start

Requirements

• 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.

Configure Your MCP Client

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

The core config block is always:

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

Alternative: run from a local build

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

> Set `PLANKA_IGNORE_SSL` to `"true"` only for self-signed certs in trusted/local environments - leave it unset in production.

Verify the Connection

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.

Client Configuration Examples

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

Standard mcpServers clients - Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Antigravity

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

>

> ```bash

> 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

> ```

Restart the client after saving.

Codex CLI

Edit `~/.codex/config.toml`:

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

Or add it in one line:

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

then set the `PLANKA_*` variables in the generated `[mcp_servers.planka-mcp.env]` block.

Continue (VS Code / JetBrains extension)

Add to `~/.continue/config.yaml`:

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"

Zed

Edit `~/.config/zed/settings.json` (macOS/Linux) or `%APPDATA%\Zed\settings.json` (Windows), or open it via Cmd+Shift+P → "zed: open settings":

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

`"source": "custom"` is required for manually-added servers (as opposed to ones installed via a Zed extension). Zed reloads the server automatically after saving - no editor restart needed.

Any other MCP-compatible client

The server is a standard stdio MCP server - any client that supports the `command` / `args` / `env` shape will work. Point it at:

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

with the four `PLANKA_*` environment variables set as shown above.

Environment Variables

Security

• 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=true` should only be used in trusted local or self-hosted environments.

Troubleshooting

The client can't see any tools / connection fails silently

• Confirm `PLANKA_BASE_URL` has 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.

SSL / certificate errors

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

Cards are created but checklists/subtasks aren't showing

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

Development

# 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 instance requires Docker Compose and is available at

`http://localhost:3000` (login: `admin@example.com` / `admin`). Update `.env` with

that URL and login for local use. As with any newly created MCP account, sign in

through the browser and accept the terms of service before using the account with the

MCP server. Stop the instance while preserving its data with `npm run planka:down`,

or stop it and delete its volumes with `npm run planka:clear`.

Seed a Demo Board

The development-only seed command creates a representative board for local testing and

demonstrations. Install the project dependencies and configure `.env` with a reachable Planka v2

instance and valid `PLANKA_BASE_URL`, `PLANKA_AGENT_EMAIL`, and `PLANKA_AGENT_PASSWORD` values

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 

# Choose a different board name
npm run seed -- --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-name` to 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.

Contributing

Contributions are welcome. See CONTRIBUTING.md for details.

Acknowledgements

This project is forked from Navya-Tecnologia/planka-v2-mcp, which builds on bradrisse/kanban-mcp. Thanks to @virapa and @bradrisse for the foundation behind this codebase.

License

Licensed under the MIT License. See LICENSE for details.

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