Planka V2

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

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

Project setup completed successfully.

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

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

card_manager with action: "get_details" includes an attachments array with read-only metadata: attachment and card IDs, creator user ID, name, type, MIME type, size, download or link URL, and timestamps. It does not download or return attachment contents.

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

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", "@goldpulpy/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"
      }
    }
  }
}

[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 = "[email protected]"
PLANKA_AGENT_PASSWORD = "your-secure-password"
PLANKA_IGNORE_SSL = "true"

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

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: [email protected]
      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": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "true"
      }
    }
  }
}

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

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

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 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 official Planka documentation.