Skip to main content
Glama
mcp-vibekanban

mcp-vibekanban

by yigitkonur

MCP server that bridges your AI coding assistant to Vibe Kanban. manage tasks, start sessions, send follow-ups, monitor execution — all without leaving Claude Code, Cursor, Amp, or whatever you're using.

VIBE_PROJECT_ID=<uuid> npx mcp-better-vibe-kanban

locks to a single project at startup so every tool call is zero-boilerplate. no project IDs in every request.

node TypeScript license


what it does

12 MCP tools and 5 MCP resources exposed over STDIO, HTTP, or Cloudflare Workers.

tools

task management:

tool

what it does

get_context

project name, active task, workspace info

list_tasks

filter by status, configurable limit

create_task

create with @tag expansion in descriptions

get_task

full task details by ID

update_task

title, description, status — any combination

delete_task

irreversible delete

session management:

tool

what it does

start_workspace_session

spin up a session for any executor (Claude Code, Amp, Gemini, Codex, Cursor, etc.)

list_sessions

all sessions in a workspace

get_session

session details by ID

send_message

follow-up with auto-queue fallback if session is busy. supports MCP task primitives for async tracking

monitoring:

tool

what it does

get_queue_status

check if a message is queued

cancel_queue

drop the queued message

resources

URI

description

vibe://tasks

all tasks in the project

vibe://context

workspace context (when VIBE_WORKSPACE_ID is set)

vibe://tasks/{taskId}

single task details

vibe://sessions/{sessionId}

session details

vibe://sessions/{sessionId}/queue

queue status

resources support subscriptions — polls on a configurable interval, emits updates on change via SHA-256 diffing.

Related MCP server: vibecompass-mcp

install

# run directly
VIBE_PROJECT_ID=<uuid> npx mcp-better-vibe-kanban

# legacy aliases still work
npx vibe-kanban-better-mcp
npx vkb-mcp

or build from source:

git clone https://github.com/yigitkonur/mcp-better-vibe-kanban.git
cd mcp-better-vibe-kanban
pnpm install && pnpm build

requires Node.js 18+ and a running Vibe Kanban instance (default: npx vibe-kanban on port 9119).

configuration

variable

default

description

VIBE_PROJECT_ID

—

required. UUID of the project to lock onto

VIBE_REPO_ID

auto-detected

repo UUID. auto-fetched if project has exactly one repo

VIBE_API_URL

http://localhost:9119

Vibe Kanban API base URL

VIBE_WORKSPACE_ID

—

enables vibe://context resource and get_context tool

VIBE_RESOURCE_POLL_INTERVAL

10000

resource subscription poll interval (ms)

MCP_TRANSPORT

stdio

stdio or http

MCP_PORT

3000

port for HTTP transport

client setup

Claude Desktop

{
  "mcpServers": {
    "mcp-better-vibe-kanban": {
      "command": "npx",
      "args": ["-y", "mcp-better-vibe-kanban"],
      "env": {
        "VIBE_PROJECT_ID": "your-project-uuid",
        "VIBE_REPO_ID": "your-repo-uuid",
        "VIBE_API_URL": "http://localhost:9119"
      }
    }
  }
}

Cursor

same structure, drop it in your Cursor MCP config.

HTTP transport

MCP_TRANSPORT=http MCP_PORT=3000 VIBE_PROJECT_ID=<uuid> npx mcp-better-vibe-kanban

health check at GET /health, MCP endpoint at POST /mcp. each HTTP session gets its own isolated server instance.

Cloudflare Workers

wrangler deploy

uses Durable Objects with SQLite migrations. progress notifications and task primitives don't work in the Workers runtime.

transports

transport

use case

command

STDIO (default)

Claude Desktop, Cursor, local clients

VIBE_PROJECT_ID=<uuid> npx mcp-better-vibe-kanban

HTTP

remote/multi-session

MCP_TRANSPORT=http MCP_PORT=3000 ...

Cloudflare Workers

edge deployment

wrangler deploy

internals

single API client (src/api/client.ts) that uses curl via spawnSync instead of native fetch — works around an ARM64 macOS socket issue where Node.js fetch gets EHOSTUNREACH on LAN IPs. blocks the event loop, but reliable.

src/
  index.ts            — MCP server factory, transport setup
  config.ts           — env var loading, UUID validation
  tools/
    index.ts          — all 12 tool definitions (Zod schemas + handlers)
  api/
    client.ts         — VibeClient singleton, curl-based HTTP
    types.ts          — TypeScript interfaces for API responses
  resources.ts        — MCP resources, subscription manager with SHA-256 change detection
  tasks.ts            — MCP task primitive integration (experimental)
  utils/
    formatter.ts      — response formatting
    progress.ts       — progress notification emitter

worker.ts             — Cloudflare Workers entry point (compiled by Wrangler, excluded from tsconfig)

dev

pnpm dev              # hot reload via tsx
pnpm build            # compile to dist/
pnpm start            # run dist/index.js
pnpm clean            # remove dist/

license

MIT

Available Tools

12 tools
cancel_queueB

Cancel a queued message.

Remove pending message from queue.

cancel_queue(session_id="sess123...")

Inputs: session_id (required).

create_taskA

Create a new task.

Add a task to the project. Supports @tagname expansion in description.

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

Inputs: title (required), description.

delete_taskA

Delete a task permanently.

Remove a task from the project. Cannot be undone.

delete_task(task_id="abc123...")

Inputs: task_id (required).

get_contextA

Get current workspace context.

Check active project, task, and workspace info.

<when_not_to_use>

  • To list tasks → use list_tasks

  • To get task details → use get_task </when_not_to_use>

get_context()

Inputs: no named parameters.

get_queue_statusB

Check if a message is queued for a session.

See pending message when executor is busy.

get_queue_status(session_id="sess123...")

Inputs: session_id (required).

get_sessionA

Get session details.

Check which executor is assigned and session state.

get_session(session_id="sess123...")

Inputs: session_id (required).

get_taskA

Get task details.

View full task information including description.

get_task(task_id="abc123...")

Inputs: task_id (required).

list_sessionsA

List sessions in a workspace.

See all executor sessions for a workspace. Each session tracks conversation with one executor.

list_sessions(workspace_id="xyz789...")

Inputs: workspace_id (required).

list_tasksA

List tasks in the project.

View all tasks or filter by status (todo, inprogress, inreview, done, cancelled).

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

Inputs: limit, status.

send_messageA

Send a message to a coding agent session.

Send follow-up instructions to an active session. Auto-queues if executor is busy.

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

Inputs: prompt (required), session_id (required), variant, executor, +1 more.

start_workspace_sessionB

Start a coding session for a task.

Launch a coding agent to work on a task. Creates workspace + session.

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

Inputs: task_id (required), executor (required), variant, base_branch.

update_taskB

Update task properties.

Change task title, description, or status.

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

Inputs: task_id (required), title, status, description.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool targets a distinct action and resource. Task tools (create, read, update, delete) are clearly separated from session tools (start, list, get, send, cancel, queue status) and context retrieval. No overlap or ambiguity.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., create_task, list_sessions, get_queue_status). The verbs are descriptive and the pattern is uniform across the entire set.

    Tool Count5/5

    With 12 tools, the server covers task management (CRUD), session lifecycle, queue operations, and workspace context. The count feels well-balanced for the domain without being excessive or sparse.

    Completeness4/5

    Task CRUD is fully covered. Sessions have start, list, get, and message sending. Lacks an explicit end/close session tool, but the current set supports core workflows. Minor gap, but agents can manage via cancel_queue or context.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers