{"_id":"@albertgroop/planka-v2-mcp","name":"@albertgroop/planka-v2-mcp","dist-tags":{"latest":"1.1.0"},"versions":{"1.1.0":{"name":"@albertgroop/planka-v2-mcp","version":"1.1.0","description":"MCP server for Planka v2.x Kanban board (with API key / X-Api-Key auth support)","license":"MIT","author":{"name":"goldpulpy","email":"sawsani1928@gmail.com"},"contributors":[{"name":"Hubert de Rocquigny","email":"hubert@rocquigny.fr"}],"homepage":"https://github.com/Albertgroop/planka-v2-mcp","bugs":{"url":"https://github.com/Albertgroop/planka-v2-mcp/issues"},"repository":{"type":"git","url":"git+https://github.com/Albertgroop/planka-v2-mcp.git"},"type":"module","engines":{"node":">=18.0.0"},"bin":{"planka-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"build":"shx rm -rf dist && tsc && shx chmod +x dist/*.js","watch":"tsc --watch","inspector":"cross-env SERVER_PORT=3008 CLIENT_PORT=5174 DOTENV_CONFIG_PATH=.env npx -y @modelcontextprotocol/inspector node -r dotenv/config dist/index.js","test":"node --experimental-vm-modules node_modules/jest/bin/jest.js tests --testPathIgnorePatterns=tests/integration.test.ts","test:coverage":"npm test -- --coverage","test:integration":"node --experimental-vm-modules node_modules/jest/bin/jest.js tests/integration.test.ts","lint":"biome check .","lint:fix":"biome check --write .","format":"biome format .","format:fix":"biome format --write .","typecheck":"tsc --noEmit","qc":"npm run typecheck && npm run lint && npm run build && npm run test","seed":"shx rm -rf .seed-dist && tsc -p tsconfig.seed.json && shx cp scripts/seed-cards.json .seed-dist/scripts/seed-cards.json && node -r dotenv/config .seed-dist/scripts/seed.js","planka:up":"docker compose -f dev/docker-compose.yml up -d","planka:down":"docker compose -f dev/docker-compose.yml down","planka:clear":"docker compose -f dev/docker-compose.yml down --volumes --remove-orphans","clear":"shx rm -rf dist .seed-dist node_modules","prepublishOnly":"npm run qc"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","node-fetch":"^3.3.2","universal-user-agent":"^7.0.2","zod":"^3.22.4","zod-to-json-schema":"^3.23.5"},"devDependencies":{"@biomejs/biome":"^2.5.2","@jest/globals":"^29.7.0","@types/jest":"^29.5.14","@types/node":"^22","cross-env":"^10.1.0","dotenv":"^17.4.2","jest":"^29.7.0","shx":"^0.3.4","ts-jest":"^29.2.6","typescript":"^5.6.2"},"_id":"@albertgroop/planka-v2-mcp@1.1.0","gitHead":"44b96b0b13cc2a41ef1b4988cca698ef73ae5c71","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-+FFfwAC3i61sLAAPMaq9Q6Zs+k+egOvgu6ZmOgLiAKPuchMBdVAPwWTi7Au7Z7TRRr5UnYCPZrbZ4RgQXt1a3A==","shasum":"4c734ec9e6d0e5f5117a865fc2a3953ca8e49ef6","tarball":"https://registry.npmjs.org/@albertgroop/planka-v2-mcp/-/planka-v2-mcp-1.1.0.tgz","fileCount":26,"unpackedSize":172735,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@albertgroop%2fplanka-v2-mcp@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDTmokYYEOKyixuBUjElFBFs0AqbftJdQMGOwk1WIepoAIhAMxmmRv6m9UYMjUskQ8RuGed4HuUpsRWtRiSpKu9DYPK"}]},"_npmUser":{"name":"hub2rock","email":"hubert@rocquigny.fr"},"directories":{},"maintainers":[{"name":"hub2rock","email":"hubert@rocquigny.fr"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/planka-v2-mcp_1.1.0_1784970598696_0.6634261130528663"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-25T09:09:58.567Z","1.1.0":"2026-07-25T09:09:58.831Z","modified":"2026-07-25T09:09:59.281Z"},"maintainers":[{"name":"hub2rock","email":"hubert@rocquigny.fr"}],"description":"MCP server for Planka v2.x Kanban board (with API key / X-Api-Key auth support)","homepage":"https://github.com/Albertgroop/planka-v2-mcp","repository":{"type":"git","url":"git+https://github.com/Albertgroop/planka-v2-mcp.git"},"contributors":[{"name":"Hubert de Rocquigny","email":"hubert@rocquigny.fr"}],"author":{"name":"goldpulpy","email":"sawsani1928@gmail.com"},"bugs":{"url":"https://github.com/Albertgroop/planka-v2-mcp/issues"},"license":"MIT","readme":"# Planka v2.x MCP\n\n**Connect Claude, Cursor, Codex, and other MCP clients directly to your Planka v2.x boards.**\n\nGive your AI agents structured, secure access to projects, boards, cards, tasks, comments, labels, and workflows through the Model Context Protocol (MCP).\n\n

\n \n \n \n \n \n \n \n \n \n \"Node.js\"\n \n \n \n \n \n \n \n \n \n \n

\n\n> [!IMPORTANT]\n> Built specifically for **Planka v2.x**. This MCP is not compatible with Planka v1.x.\n\n## Why Planka MCP?\n\nPlanka provides an excellent web interface for human users. AI agents, however, need structured access to projects, boards, cards, tasks, comments, and workflows.\n\nThis 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.\n\n## Supported Planka Versions\n\n| Planka Version | Status |\n| -------------- | ------------------- |\n| 2.0.0-rc.2 | ✅ Tested |\n| 2.1.1 | ✅ Tested |\n| Newer 2.x | ⚠️ Expected to work |\n\n## Features\n\n- Full project and board management\n- Complete card lifecycle management\n- Task Lists and tasks support\n- Comments, labels, and assignments\n- Card time tracking\n- Project and board summaries\n- MCP-native tool interface\n- Support for major MCP clients\n- Self-hosted and cloud Planka support\n
\nExample Conversations\n\n### Project Setup\n\n**User**\n\n> Create a project called \"Website Redesign\" with boards \"Backlog\", \"In Progress\", and \"Done\".\n\n**Assistant**\n\n```text\n✓ Created project \"Website Redesign\"\n✓ Created board \"Backlog\"\n✓ Created board \"In Progress\"\n✓ Created board \"Done\"\n\nProject setup completed successfully.\n```\n\n### Task Creation\n\n**User**\n\n> Create a card \"Implement authentication\" in the Backlog board with tasks:\n>\n> - Design login flow\n> - Implement JWT authentication\n> - Add password reset\n> - Write tests\n\n**Assistant**\n\n```text\n✓ Created card \"Implement authentication\"\n✓ Created task list\n✓ Added 4 tasks\n```\n\n### Workflow Automation\n\n**User**\n\n> Find all overdue cards assigned to me, move them to \"Blocked\", add a comment explaining why, and generate a project summary.\n\n**Assistant**\n\n```text\n✓ Found 7 overdue cards\n✓ Moved cards to \"Blocked\"\n✓ Added explanatory comments\n✓ Generated updated project summary\n```\n\n
\n\n
\nAvailable Tools\n\n| Tool Name | Actions | Description |\n| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- |\n| `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 |\n| `list_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | Kanban lists within a board |\n| `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 |\n| `stopwatch` | `start` · `stop` · `get` · `reset` | Time tracking on a card |\n| `label_manager` | `get_all` · `create` · `update` · `delete` · `add_to_card` · `remove_from_card` | Board labels and their assignment to cards |\n| `task_list_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | Task Lists inside a card (Planka v2.0 entity) |\n| `task_manager` | `get_all` · `create` · `batch_create` · `get_one` · `update` · `delete` · `complete_task` | Individual tasks, including bulk creation |\n| `comment_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | Comments on a card |\n| `membership_manager` | `get_all` · `create` · `get_one` · `update` · `delete` | Board-level membership and roles (`editor` / `viewer`) |\n| `card_membership_manager` | `get_all` · `get_users` · `create` · `delete` | Assign/remove card members by **ID, email, or username** |\n\n
\n\n## Quick Start\n\n### Requirements\n\n- A running Planka v2.x instance\n- A dedicated Planka user account for your AI agent\n- Node.js 18+ (if running locally)\n\n> [!IMPORTANT]\n> After creating the MCP account, log in to the Planka web interface with that account\n> and accept the terms of service before configuring or starting the MCP server. This is\n> required for every new account.\n\n### Configure Your MCP Client\n\nEvery MCP-compatible client uses the same underlying command - only the config file location (and occasionally the JSON wrapper) differs. See [Client Configuration Examples](#client-configuration-examples) below for your specific tool.\n\nThe core config block is always:\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@albertgroop/planka-v2-mcp@latest\"],\n \"env\": {\n \"PLANKA_BASE_URL\": \"https://your-planka-instance.com\",\n \"PLANKA_AGENT_EMAIL\": \"agent@yourdomain.com\",\n \"PLANKA_AGENT_PASSWORD\": \"your-secure-password\",\n \"PLANKA_IGNORE_SSL\": \"true\"\n }\n}\n```\n\n
\nAlternative: run from a local build\n\n```json\n{\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/planka-v2-mcp/dist/index.js\"],\n \"env\": {\n \"PLANKA_BASE_URL\": \"https://your-planka-instance.com\",\n \"PLANKA_AGENT_EMAIL\": \"agent@yourdomain.com\",\n \"PLANKA_AGENT_PASSWORD\": \"your-secure-password\",\n \"PLANKA_IGNORE_SSL\": \"true\"\n }\n}\n```\n\nUseful when you're contributing to the server itself or need a pinned, offline build.\n\n
\n\n> [!TIP]\n> Set `PLANKA_IGNORE_SSL` to `\"true\"` only for self-signed certs in trusted/local environments - leave it unset in production.\n\n### Verify the Connection\n\nAsk your agent something read-only first, e.g. _\"List my Planka projects.\"_ If you get a real response back, you're wired up correctly.\n\n## Client Configuration Examples\n\nMost 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.\n\n
\nStandard mcpServers clients - Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Antigravity\n
\n\n```json\n{\n \"mcpServers\": {\n \"planka-mcp\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@albertgroop/planka-v2-mcp@latest\"],\n \"env\": {\n \"PLANKA_BASE_URL\": \"https://your-planka-instance.com\",\n \"PLANKA_AGENT_EMAIL\": \"agent@yourdomain.com\",\n \"PLANKA_AGENT_PASSWORD\": \"your-secure-password\",\n \"PLANKA_IGNORE_SSL\": \"true\"\n }\n }\n }\n}\n```\n\nDrop this block into the relevant config file:\n\n| Client | Config file |\n| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Claude Desktop** | macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · Windows: `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| **Claude Code (CLI)** | `.mcp.json` in your project root (or `claude mcp add`, see below) |\n| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |\n| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |\n| **Cline** (VS Code) | `cline_mcp_settings.json`, via **Cline → MCP Servers → Configure MCP Servers** (add `\"disabled\": false, \"autoApprove\": []` to the server entry) |\n| **Antigravity** | Via **Settings → MCP Servers → Add Server**, or its config file directly |\n\n> [!NOTE]\n> Claude Code also supports adding the server via a one-liner instead of hand-editing JSON:\n>\n> ```bash\n> claude mcp add planka-mcp \\\n> --env PLANKA_BASE_URL=https://your-planka-instance.com \\\n> --env PLANKA_AGENT_EMAIL=agent@yourdomain.com \\\n> --env PLANKA_AGENT_PASSWORD=your-secure-password \\\n> --env PLANKA_IGNORE_SSL=true \\\n> -- npx -y @albertgroop/planka-v2-mcp@latest\n> ```\n\nRestart the client after saving.\n\n
\n\n
\nCodex CLI\n
\n\nEdit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.planka-mcp]\ncommand = \"npx\"\nargs = [\"-y\", \"@albertgroop/planka-v2-mcp@latest\"]\n\n[mcp_servers.planka-mcp.env]\nPLANKA_BASE_URL = \"https://your-planka-instance.com\"\nPLANKA_AGENT_EMAIL = \"agent@yourdomain.com\"\nPLANKA_AGENT_PASSWORD = \"your-secure-password\"\nPLANKA_IGNORE_SSL = \"true\"\n```\n\nOr add it in one line:\n\n```bash\ncodex mcp add planka-mcp -- npx -y @albertgroop/planka-v2-mcp@latest\n```\n\nthen set the `PLANKA_*` variables in the generated `[mcp_servers.planka-mcp.env]` block.\n\n
\n\n
\nContinue (VS Code / JetBrains extension)\n
\n\nAdd to `~/.continue/config.yaml`:\n\n```yaml\nmcpServers:\n - name: planka-mcp\n command: npx\n args:\n - -y\n - \"@albertgroop/planka-v2-mcp@latest\"\n env:\n PLANKA_BASE_URL: https://your-planka-instance.com\n PLANKA_AGENT_EMAIL: agent@yourdomain.com\n PLANKA_AGENT_PASSWORD: your-secure-password\n PLANKA_IGNORE_SSL: \"true\"\n```\n\n
\n\n
\nZed\n
\n\nEdit `~/.config/zed/settings.json` (macOS/Linux) or `%APPDATA%\\Zed\\settings.json` (Windows), or open it via **Cmd+Shift+P → \"zed: open settings\"**:\n\n```json\n{\n \"context_servers\": {\n \"planka-mcp\": {\n \"source\": \"custom\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@albertgroop/planka-v2-mcp@latest\"],\n \"env\": {\n \"PLANKA_BASE_URL\": \"https://your-planka-instance.com\",\n \"PLANKA_AGENT_EMAIL\": \"agent@yourdomain.com\",\n \"PLANKA_AGENT_PASSWORD\": \"your-secure-password\",\n \"PLANKA_IGNORE_SSL\": \"true\"\n }\n }\n }\n}\n```\n\n`\"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.\n\n
\n\n
\nAny other MCP-compatible client\n
\n\nThe server is a standard stdio MCP server - any client that supports the `command` / `args` / `env` shape will work. Point it at:\n\n```bash\nnpx -y @albertgroop/planka-v2-mcp@latest\n```\n\nwith the four `PLANKA_*` environment variables set as shown above.\n\n
\n\n## Environment Variables\n\n| Variable | Required | Default | Description |\n| ----------------------- | :------: | :-----: | -------------------------------------------------------------------------- |\n| `PLANKA_BASE_URL` | ✅ | - | Full URL of your Planka instance |\n| `PLANKA_API_KEY` | ⚠️ | - | Per-user Planka API key. Alternative to email/password (see below) |\n| `PLANKA_AGENT_EMAIL` | ⚠️ | - | Login email for the dedicated agent user |\n| `PLANKA_AGENT_PASSWORD` | ⚠️ | - | Password for the agent user |\n| `PLANKA_IGNORE_SSL` | ❌ | `false` | Skip SSL verification - self-signed/local certs only |\n\n> [!NOTE]\n> ⚠️ Authentication requires **either** `PLANKA_API_KEY` **or** the\n> `PLANKA_AGENT_EMAIL` + `PLANKA_AGENT_PASSWORD` pair. If `PLANKA_API_KEY` is set it is\n> used directly and the email/password are ignored for login. See\n> [API Key Authentication](#api-key-authentication-oidc_enforced).\n\n## API Key Authentication (OIDC_ENFORCED)\n\nPlanka v2.x lets each user generate a personal API key (sent in the `X-Api-Key` header)\nthat works on every `/api/` route. Set it via `PLANKA_API_KEY` instead of the agent\nemail/password:\n\n```json\n{\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@albertgroop/planka-v2-mcp@latest\"],\n \"env\": {\n \"PLANKA_BASE_URL\": \"https://your-planka-instance.com\",\n \"PLANKA_API_KEY\": \"your-planka-api-key\",\n \"PLANKA_IGNORE_SSL\": \"true\"\n }\n}\n```\n\nThis is **required** when your Planka instance runs with `OIDC_ENFORCED=true`: in that\nmode the `POST /api/access-tokens` endpoint (email/password login) is disabled, so the\nserver cannot authenticate with a password and must use an API key.\n\nWhen `PLANKA_API_KEY` is set, `PLANKA_AGENT_PASSWORD` is not needed. You may still keep\n`PLANKA_AGENT_EMAIL` defined (without a password): it lets the admin-user lookup resolve\nthe acting user's ID for operations that need it.\n\n## Security\n\n- Authentication is performed using a dedicated Planka user account.\n- Credentials are supplied through environment variables only.\n- The MCP server does not persist board data outside the running process.\n- SSL certificate verification is enabled by default.\n- `PLANKA_IGNORE_SSL=true` should only be used in trusted local or self-hosted environments.\n\n## Troubleshooting\n\n
\nThe client can't see any tools / connection fails silently\n
\n\n- Confirm `PLANKA_BASE_URL` has no trailing slash and is reachable from the machine running the MCP server (not just your browser).\n- 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.\n\n
\n\n
\nSSL / certificate errors\n
\n\n- If your instance uses a self-signed certificate, set `\"PLANKA_IGNORE_SSL\": \"true\"`. Avoid this in production - prefer a valid certificate instead.\n\n
\n\n
\nCards are created but checklists/subtasks aren't showing\n
\n\n- Make sure the card type is `\"project\"` (the default). Cards created as `\"story\"` type don't expose Task Lists in the same way.\n\n
\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Configure environment variables\ncp .env.example .env\n\n# Start the bundled Planka development instance\nnpm run planka:up\n\n# Build the project\nnpm run build\n\n# Run @modelcontextprotocol/inspector\nnpm run inspector\n```\n\nThe development instance requires Docker Compose and is available at\n`http://localhost:3000` (login: `admin@example.com` / `admin`). Update `.env` with\nthat URL and login for local use. As with any newly created MCP account, sign in\nthrough the browser and accept the terms of service before using the account with the\nMCP server. Stop the instance while preserving its data with `npm run planka:down`,\nor stop it and delete its volumes with `npm run planka:clear`.\n\n### Seed a Demo Board\n\nThe development-only seed command creates a representative board for local testing and\ndemonstrations. Install the project dependencies and configure `.env` with a reachable Planka v2\ninstance and valid `PLANKA_BASE_URL`, `PLANKA_AGENT_EMAIL`, and `PLANKA_AGENT_PASSWORD` values\nbefore running it.\n\n```bash\n# Reuse or create the private \"Demo Project\", then create \"Demo Board\"\nnpm run seed\n\n# Seed an existing project\nnpm run seed -- --project-id \n\n# Choose a different board name\nnpm run seed -- --project-id --board-name \"My Demo Board\"\n\n# Show all options\nnpm run seed -- --help\n```\n\nThe board includes cards across the default workflow lists, descriptions, relative due dates,\nPlanka labels used as tags, task lists, completed and incomplete tasks, and comments. The command\nprints the project ID, board ID, board name, and resource counts when it succeeds.\n\nThe seed command refuses to modify a project that already contains a board with the exact requested\nname; use `--board-name` to choose another name. If an error occurs after board creation, the command\nreports the failed stage and board ID and leaves the partially populated board available for\ninspection. Delete that board in Planka before retrying with the same name.\n\nThe seed source and its separately compiled `.seed-dist/` output are development-only and are not\nincluded in the MCP server build or published package.\n\n## Contributing\n\nContributions are welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.\n\n## Acknowledgements\n\nThis project is forked from [goldpulpy/planka-v2-mcp](https://github.com/goldpulpy/planka-v2-mcp), which is itself forked from [Navya-Tecnologia/planka-v2-mcp](https://github.com/Navya-Tecnologia/planka-v2-mcp) and builds on [bradrisse/kanban-mcp](https://github.com/bradrisse/kanban-mcp). Thanks to [@goldpulpy](https://github.com/goldpulpy), [@virapa](https://github.com/virapa), and [@bradrisse](https://github.com/bradrisse) for the foundation behind this codebase.\n\n## License\n\nLicensed under the MIT License. See [LICENSE](./LICENSE) for details.\n\n

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

\n","readmeFilename":"README.md","_rev":"1-76cde8b5ed22ba23f64b20b1216a05ae"}