mcp-vibekanban

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.

---

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.

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