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

| Planka Version | Status | | -------------- | ------------------- | | 2.0.0-rc.2 | ✅ Tested | | 2.1.1 | ✅ Tested | | Newer 2.x | ⚠️ Expected to work |

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

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

| Tool Name | Actions | Description | | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | project_board_manager | get_projects · create_project · get_project · update_project · delete_project · get_boards · create_board · get_board · update_board · delete_board · get_board_summary · get_project_summary | Projects and boards, including aggregate summaries | | list_manager | get_all · create · get_one · update · delete | Kanban lists within a board | | card_manager | get_all · create · get_one · update · move · duplicate · delete · create_with_tasks · get_details | Cards, including one-shot creation with a task checklist | | stopwatch | start · stop · get · reset | Time tracking on a card | | label_manager | get_all · create · update · delete · add_to_card · remove_from_card | Board labels and their assignment to cards | | task_list_manager | get_all · create · get_one · update · delete | Task Lists inside a card (Planka v2.0 entity) | | task_manager | get_all · create · batch_create · get_one · update · delete · complete_task | Individual tasks, including bulk creation | | comment_manager | get_all · create · get_one · update · delete | Comments on a card | | membership_manager | get_all · create · get_one · update · delete | Board-level membership and roles (editor / viewer) | | card_membership_manager | get_all · get_users · create · delete | Assign/remove card members by ID, email, or username |

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", "@albertgroop/planka-v2-mcp@latest"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_AGENT_EMAIL": "[email protected]",
    "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": "[email protected]",
    "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.

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

Drop this block into the relevant config file:

| Client | Config file | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | Claude Desktop | macOS: ~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json | | Claude Code (CLI) | .mcp.json in your project root (or claude mcp add, see below) | | Cursor | ~/.cursor/mcp.json (global) or .cursor/mcp.json (project) | | Windsurf | ~/.codeium/windsurf/mcp_config.json | | Cline (VS Code) | cline_mcp_settings.json, via Cline → MCP Servers → Configure MCP Servers (add "disabled": false, "autoApprove": [] to the server entry) | | Antigravity | Via Settings → MCP Servers → Add Server, or its config file directly |

[!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 [email protected] \
  --env PLANKA_AGENT_PASSWORD=your-secure-password \
  --env PLANKA_IGNORE_SSL=true \
  -- npx -y @albertgroop/planka-v2-mcp@latest

Restart the client after saving.

Edit ~/.codex/config.toml:

[mcp_servers.planka-mcp]
command = "npx"
args = ["-y", "@albertgroop/planka-v2-mcp@latest"]

[mcp_servers.planka-mcp.env]
PLANKA_BASE_URL = "https://your-planka-instance.com"
PLANKA_AGENT_EMAIL = "[email protected]"
PLANKA_AGENT_PASSWORD = "your-secure-password"
PLANKA_IGNORE_SSL = "true"

Or add it in one line:

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

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

Add to ~/.continue/config.yaml:

mcpServers:
  - name: planka-mcp
    command: npx
    args:
      - -y
      - "@albertgroop/planka-v2-mcp@latest"
    env:
      PLANKA_BASE_URL: https://your-planka-instance.com
      PLANKA_AGENT_EMAIL: [email protected]
      PLANKA_AGENT_PASSWORD: your-secure-password
      PLANKA_IGNORE_SSL: "true"

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", "@albertgroop/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "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.

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

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

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

Environment Variables

| Variable | Required | Default | Description | | ----------------------- | :------: | :-----: | -------------------------------------------------------------------------- | | PLANKA_BASE_URL | ✅ | - | Full URL of your Planka instance | | PLANKA_API_KEY | ⚠️ | - | Per-user Planka API key. Alternative to email/password (see below) | | PLANKA_AGENT_EMAIL | ⚠️ | - | Login email for the dedicated agent user | | PLANKA_AGENT_PASSWORD | ⚠️ | - | Password for the agent user | | PLANKA_IGNORE_SSL | ❌ | false | Skip SSL verification - self-signed/local certs only |

[!NOTE] ⚠️ Authentication requires either PLANKA_API_KEY or the PLANKA_AGENT_EMAIL + PLANKA_AGENT_PASSWORD pair. If PLANKA_API_KEY is set it is used directly and the email/password are ignored for login. See API Key Authentication.

API Key Authentication (OIDC_ENFORCED)

Planka v2.x lets each user generate a personal API key (sent in the X-Api-Key header) that works on every /api/ route. Set it via PLANKA_API_KEY instead of the agent email/password:

{
  "command": "npx",
  "args": ["-y", "@albertgroop/planka-v2-mcp@latest"],
  "env": {
    "PLANKA_BASE_URL": "https://your-planka-instance.com",
    "PLANKA_API_KEY": "your-planka-api-key",
    "PLANKA_IGNORE_SSL": "true"
  }
}

This is required when your Planka instance runs with OIDC_ENFORCED=true: in that mode the POST /api/access-tokens endpoint (email/password login) is disabled, so the server cannot authenticate with a password and must use an API key.

When PLANKA_API_KEY is set, PLANKA_AGENT_PASSWORD is not needed. You may still keep PLANKA_AGENT_EMAIL defined (without a password): it lets the admin-user lookup resolve the acting user's ID for operations that need it.

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

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

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

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: [email protected] / 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 <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-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 goldpulpy/planka-v2-mcp, which is itself forked from Navya-Tecnologia/planka-v2-mcp and builds on bradrisse/kanban-mcp. Thanks to @goldpulpy, @virapa, and @bradrisse for the foundation behind this codebase.

License

Licensed under the MIT License. See LICENSE for details.