mcp-vibekanban

📋 Vibe Kanban MCP 📋

Stop context-switching. Start shipping from your AI session.

The MCP bridge between your AI coding assistant and Vibe Kanban. Create tasks, launch workspace sessions, and message coding agents — all without leaving your editor.

  •  

🧭 Quick Navigation

⚡ Get Started • 🎯 Why mcp-vibekanban • 🎮 Tools • ⚙️ Configuration • 📚 Workflows

The Pitch

mcp-vibekanban is the project management backbone for your AI coding assistant. Instead of alt-tabbing to a Kanban board, your AI creates tasks, launches coding agent sessions, and sends follow-up messages — all through MCP. Project and repo IDs are locked via environment variables, so every tool call is clean and minimal.

📋 Task Management Create, list, update, delete

🚀 Workspace Sessions Launch any coding agent

💬 Session Messaging Follow-up + auto-queue

🔒 Env-Locked IDs No ID juggling per call

Here's how it works:

• You: "Create a task for adding OAuth, then start a Claude Code session on it."
• AI + mcp-vibekanban: Creates the task, launches a workspace session, and gives you the session ID.
• You: "Send a follow-up: add Google as an OAuth provider."
• Result: The message is delivered (or auto-queued if the agent is busy). Zero browser tabs opened.

🎯 Why mcp-vibekanban

The official Vibe Kanban MCP requires passing project_id and repo_id in every call. mcp-vibekanban locks those via env vars and adds session messaging.

❌ Old Way (Official MCP)	✅ New Way (mcp-vibekanban)
Call list_projects to find your project ID. Call list_repos to find your repo ID. Pass both IDs in every single tool call. No way to message active sessions. 13 tools with boilerplate in each call.	Set env vars once — IDs are locked. create_task(title="Add auth") — done. Launch sessions, send messages, check queues. Auto-queue when executor is busy. 12 focused tools, zero boilerplate. ☕

🚀 Get Started in 60 Seconds

1. Prerequisites

You need Vibe Kanban running (the upstream project):

npx vibe-kanban              # default port 9119
# or: PORT=1990 npx vibe-kanban

2. Configure Your MCP Client

Client	Config File	Docs
🖥️ Claude Desktop	claude_desktop_config.json	Setup
⌨️ Claude Code	CLI or ~/.claude.json	Setup
🎯 Cursor / 🏄 Windsurf	.cursor/mcp.json	Setup

Claude Desktop

Quick install:

npx install-mcp mcp-vibekanban --client claude-desktop \
  --env VKB_API_URL=https://your-vibekanban-instance.com \
  --env VKB_PROJECT_SLUG=your-project \
  --env VKB_REPOSITORY_SLUG=your-repo

Manual config — add to claude_desktop_config.json:

{
  "mcpServers": {
    "vibekanban": {
      "command": "npx",
      "args": ["-y", "mcp-vibekanban"],
      "env": {
        "VKB_API_URL": "https://your-vibekanban-instance.com",
        "VKB_PROJECT_SLUG": "your-project",
        "VKB_REPOSITORY_SLUG": "your-repo"
      }
    }
  }
}

Claude Code CLI

claude mcp add vibekanban npx \
  --scope user \
  --env VKB_API_URL=https://your-vibekanban-instance.com \
  --env VKB_PROJECT_SLUG=your-project \
  --env VKB_REPOSITORY_SLUG=your-repo \
  -- -y mcp-vibekanban

Or manually add to ~/.claude.json:

{
  "mcpServers": {
    "vibekanban": {
      "command": "npx",
      "args": ["-y", "mcp-vibekanban"],
      "env": {
        "VKB_API_URL": "https://your-vibekanban-instance.com",
        "VKB_PROJECT_SLUG": "your-project",
        "VKB_REPOSITORY_SLUG": "your-repo"
      }
    }
  }
}

Cursor/Windsurf

Add to .cursor/mcp.json (or equivalent):

{
  "mcpServers": {
    "vibekanban": {
      "command": "npx",
      "args": ["-y", "mcp-vibekanban"],
      "env": {
        "VKB_API_URL": "https://your-vibekanban-instance.com",
        "VKB_PROJECT_SLUG": "your-project",
        "VKB_REPOSITORY_SLUG": "your-repo"
      }
    }
  }
}

Backward Compatibility: The old package name vibe-kanban-better-mcp still works as a binary alias. Existing configs don't need updating.

🌐 Transport Modes

Vibe Kanban supports three transport modes:

Mode	Use Case	How to Start
STDIO (default)	Claude Desktop, Cursor, Windsurf	npx mcp-vibekanban
HTTP Streamable	Self-hosted, Docker, LAN sharing	MCP_TRANSPORT=http npx mcp-vibekanban
Cloudflare Workers	Serverless, globally distributed	Already deployed ↓

Remote MCP (Cloudflare Workers)

A remote MCP endpoint is deployed and ready to use:

https://mcp-vibekanban.seodoold.workers.dev/mcp

Connect from any MCP client that supports HTTP Streamable transport:

{
  "mcpServers": {
    "vibekanban-remote": {
      "type": "streamable-http",
      "url": "https://mcp-vibekanban.seodoold.workers.dev/mcp"
    }
  }
}

Self-Hosted HTTP Streamable

# Start on default port 3001
MCP_TRANSPORT=http npx mcp-vibekanban

# Custom port
MCP_TRANSPORT=http MCP_PORT=8080 npx mcp-vibekanban

{
  "mcpServers": {
    "vibekanban-http": {
      "type": "streamable-http",
      "url": "http://localhost:3001/mcp"
    }
  }
}

🎮 Tool Reference

mcp-vibekanban exposes 12 MCP tools across three categories:

📋 get_context Workspace info	📝 list_tasks Filter & browse	➕ create_task New task	🔍 get_task Full details	✏️ update_task Edit & transition	🗑️ delete_task Remove task
🚀 start_workspace_session Launch agent	📂 list_sessions All sessions	📍 get_session Session info	💬 send_message Follow-up	📤 get_queue_status Pending check	🚫 cancel_queue Clear queue

Task Management

get_context

Get current workspace context — project, active task, and workspace info.

Parameter	Type	Required	Description
(none)	—	—	No parameters needed

get_context()

list_tasks

List tasks in the project, optionally filtered by status.

Parameter	Type	Required	Default	Description
status	string	No	all	todo · inprogress · inreview · done · cancelled
limit	number	No	50	Max results (1–100)

list_tasks(status="inprogress", limit=10)

create_task

Create a new task. Supports @tag expansion in descriptions.

Parameter	Type	Required	Description
title	string	Yes	Task title (1–500 chars)
description	string	No	Details, supports @tag expansion

create_task(title="Add user auth", description="Implement OAuth with @google-auth")

get_task

Get full task details by ID.

Parameter	Type	Required	Description
task_id	string (UUID)	Yes	Task UUID

get_task(task_id="abc123...")

update_task

Update task title, description, or status. At least one field required.

Parameter	Type	Required	Description
task_id	string (UUID)	Yes	Task UUID
title	string	No	New title
description	string	No	New description
status	string	No	todo · inprogress · inreview · done · cancelled

update_task(task_id="abc123...", status="done")

delete_task

Permanently delete a task. Cannot be undone.

Parameter	Type	Required	Description
task_id	string (UUID)	Yes	Task UUID

delete_task(task_id="abc123...")

Session Management

start_workspace_session

Launch a coding agent session for a task. Creates workspace + session.

Parameter	Type	Required	Description
task_id	string (UUID)	Yes	Task UUID
executor	string	Yes	claude_code · amp · gemini · codex · opencode · cursor · qwen_code · copilot · droid
variant	string	No	e.g., PLAN, IMPLEMENT
base_branch	string	No	Branch to work from (default: main)

start_workspace_session(task_id="abc123...", executor="claude_code")

list_sessions

List all sessions for a workspace.

Parameter	Type	Required	Description
workspace_id	string (UUID)	Yes	Workspace UUID

list_sessions(workspace_id="xyz789...")

get_session

Get session details including assigned executor.

Parameter	Type	Required	Description
session_id	string (UUID)	Yes	Session UUID

get_session(session_id="sess123...")

Messaging

send_message

Send a follow-up message to an active coding agent session. Auto-queues if the executor is busy.

Parameter	Type	Required	Default	Description
session_id	string (UUID)	Yes	—	Session UUID
prompt	string	Yes	—	Message to send
executor	string	No	auto	Auto-detected from session
variant	string	No	—	e.g., PLAN
auto_queue	boolean	No	true	Queue message if executor is busy

send_message(session_id="sess123...", prompt="Add error handling for edge cases")

get_queue_status

Check if a message is queued for a session.

Parameter	Type	Required	Description
session_id	string (UUID)	Yes	Session UUID

get_queue_status(session_id="sess123...")

cancel_queue

Cancel a pending queued message.

Parameter	Type	Required	Description
session_id	string (UUID)	Yes	Session UUID

cancel_queue(session_id="sess123...")

⚙️ Environment Variables

Variable	Required	Default	Description
VKB_API_URL	✅ Yes	—	Vibe Kanban instance URL (e.g., https://your-instance.com)
VKB_PROJECT_SLUG	✅ Yes	—	Project slug or UUID — locked for all tool calls
VKB_REPOSITORY_SLUG	✅ Yes	—	Repository slug or UUID — locked for all tool calls

All three variables are required and lock the project/repository context so you never need to pass IDs in individual tool calls.

📚 Recommended Workflows

Create → Launch → Message

The most common pattern: create a task, start a session, and iterate with follow-ups.

1. create_task(title="Add OAuth login")
   → Returns task_id

2. start_workspace_session(task_id="...", executor="claude_code")
   → Returns workspace_id

3. list_sessions(workspace_id="...")
   → Returns session_id

4. send_message(session_id="...", prompt="Add Google as a provider")
   → Sent (or auto-queued if busy)

5. get_queue_status(session_id="...")
   → Check pending messages

Triage & Prioritize

Review existing tasks and move them through your pipeline.

1. list_tasks(status="todo")
   → See all pending work

2. get_task(task_id="...")
   → Read full details

3. update_task(task_id="...", status="inprogress")
   → Move to active

4. start_workspace_session(task_id="...", executor="amp")
   → Hand off to a coding agent

Multi-Agent Orchestration

Run different agents on different tasks simultaneously.

1. create_task(title="Refactor auth module")
2. create_task(title="Write API tests")
3. create_task(title="Update migration guide")

4. start_workspace_session(task_id="task1", executor="claude_code")
5. start_workspace_session(task_id="task2", executor="gemini")
6. start_workspace_session(task_id="task3", executor="copilot")

🛠️ Development

git clone https://github.com/yigitkonur/mcp-vibekanban.git
cd mcp-vibekanban
npm install
npm run dev        # Run with tsx (hot reload)
npm run build      # Compile TypeScript
npm start          # Run compiled output

Project Structure

src/
├── index.ts          # Server entry point
├── config.ts         # Env var loader & validation
├── tools/
│   └── index.ts      # All 12 tool definitions
├── api/              # Vibe Kanban HTTP client
├── resources.ts      # MCP resource handlers
├── tasks.ts          # Task primitive integration
└── utils/            # Formatter & progress helpers

🔧 Troubleshooting

Expand for troubleshooting tips

Problem	Solution
Server exits with "VKB_PROJECT_SLUG is required"	Set all three required env vars: VKB_API_URL, VKB_PROJECT_SLUG, VKB_REPOSITORY_SLUG.
Connection refused / ECONNREFUSED	Make sure your Vibe Kanban instance is running and VKB_API_URL is correct.
EHOSTUNREACH on Apple Silicon	The HTTP client uses curl subprocess to work around ARM64 macOS network issues with Node.js native clients. Ensure curl is available.
"Unknown tool" error	Verify you're on the latest version: npx mcp-vibekanban@latest.
Send message returns "executor busy"	This is normal. With auto_queue: true (default), the message is automatically queued and will execute when the current process completes.
Task ID format error	All IDs must be valid UUIDs (e.g., 123e4567-e89b-12d3-a456-426614174000).
Old binary name still works?	Yes — vibe-kanban-better-mcp and vkb-mcp are kept as binary aliases for backward compatibility.

MIT © Yiğit Konur

Vibe Kanban · MCP Protocol · install-mcp