🔄 Kanban MCP

Welcome to the Kanban MCP project! 🎉 This project integrates Planka kanban boards with Cursor's Machine Control Protocol (MCP) to enable AI assistants like Claude to manage your kanban boards.

🤔 What is Kanban MCP?

Kanban MCP is a bridge between Planka (an open-source kanban board) and Cursor's Machine Control Protocol. It allows AI assistants like Claude to:

• 📋 View and manage projects, boards, lists, and cards
• ✅ Create and update tasks
• 💬 Add comments to cards
• 🔄 Move cards between lists
• ⏱️ Track time spent on tasks
• 🚀 And much more!

This integration enables a seamless workflow where you can ask Claude to help manage your development tasks, track progress, and organize your work.

🚦 Quick Start

📋 Prerequisites

• 🟢 Node.js (version 18 or above)
• 🐳 Docker for running Planka (or an existing Planka instance)

🚀 Usage with npx (recommended)

No installation required — just configure your MCP client to run the server via npx:

Claude Desktop / Cursor

Add this to your MCP configuration (claude_desktop_config.json or .cursor/mcp.json):

{
  "mcpServers": {
    "planka": {
      "command": "npx",
      "args": ["-y", "@borgius/mcp-planka"],
      "env": {
        "PLANKA_BASE_URL": "http://localhost:3333",
        "PLANKA_AGENT_EMAIL": "[email protected]",
        "PLANKA_AGENT_PASSWORD": "demo"
      }
    }
  }
}

Global install (alternative)

npm install -g @borgius/mcp-planka
mcp-planka

🐳 Running Planka with Docker

If you don't have a Planka instance yet, clone this repo and start one:

git clone https://github.com/bradrisse/kanban-mcp.git
cd kanban-mcp
npm run up

• Default URL: http://localhost:3333
• Default credentials: [email protected] / demo

For Docker-based deployment and other advanced options, see the Installation Guide.

📚 Documentation

For Users

• 🛠️ Installation Guide: How to install and configure Kanban MCP
• 📝 Usage Guide: How to use Kanban MCP with Claude
• 💡 Capabilities and Strategies: Detailed exploration of MCP server capabilities and LLM interaction strategies
• ⚠️ Troubleshooting: Solutions to common issues

For Developers

• 👨‍💻 Developer Guide: Information for developers who want to contribute to or modify Kanban MCP
• 📖 API Reference: Detailed documentation of the MCP commands and Planka API integration

✨ Features

Kanban MCP provides a comprehensive set of features for managing your kanban boards:

📂 Project Management

• Create and view projects
• Manage project settings and members

📊 Board Management

• Create and view boards within projects
• Customize board settings

📋 List Management

• Create and organize lists within boards
• Reorder lists as needed

🗂️ Card Management

• Create, update, and delete cards
• Move cards between lists
• Add descriptions, due dates, and labels
• Duplicate cards to create templates

⏱️ Time Tracking

• Start, stop, and reset stopwatches
• Track time spent on individual tasks
• Analyze time usage patterns

✅ Task Management

• Create and manage tasks within cards
• Mark tasks as complete or incomplete

💬 Comment Management

• Add comments to cards for discussion
• View comment history

🤖 LLM Interaction Strategies

MCP Kanban supports several workflow strategies for LLM-human collaboration:

1. 🤝 LLM-Driven Development with Human Review: LLMs implement tasks while humans review and provide feedback
2. 👥 Human-Driven Development with LLM Support: Humans implement while LLMs provide analysis and recommendations
3. 🧠 Collaborative Grooming and Planning: Humans and LLMs work together to plan and organize tasks

For more details on these strategies, see the Capabilities and Strategies wiki page.

📦 Available npm Scripts

• npm run build: Build the TypeScript code
• npm run build-docker: Build the TypeScript code and create a Docker image
• npm run up: Start the Planka containers (kanban and postgres)
• npm run down: Stop all containers
• npm run restart: Restart the Planka containers
• npm run start-node: Start the MCP server directly with Node (for testing outside of Cursor)
• npm run release: Bump patch version, build, and publish to npm
• npm run release:minor: Bump minor version, build, and publish to npm
• npm run release:major: Bump major version, build, and publish to npm

🤝 Contributing

We welcome contributions to Kanban MCP! If you'd like to contribute:

1. Check out the Developer Guide for information on the project structure and development workflow
2. Look at the open issues for tasks that need help
3. Submit a pull request with your changes

🆘 Support

If you need help with Kanban MCP:

1. Check the Troubleshooting page for solutions to common issues
2. Search the GitHub issues to see if your problem has been reported
3. Open a new issue if you can't find a solution

📜 License

Kanban MCP is open-source software licensed under the MIT License. See the LICENSE file for details.