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

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.

🚀 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:

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

| 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