vibe-kanban/docs/integrations/vibe-kanban-mcp-server.mdx

---
title: "Vibe Kanban MCP Server"
description: "Configure the Vibe Kanban MCP server"
---

Vibe Kanban exposes a local MCP (Model Context Protocol) server, allowing you to manage projects and tasks from external MCP clients like Claude Desktop, Raycast, or even coding agents running within Vibe Kanban itself.

<Note>
This page covers connecting **external MCP clients** to Vibe Kanban's MCP server. For configuring MCP servers **within** Vibe Kanban for your coding agents, see the [MCP Server Configuration](/integrations/mcp-server-configuration) guide.
</Note>

<Info>
Vibe Kanban's MCP server is **local-only** - it runs on your computer and can only be accessed by applications installed locally. It cannot be accessed via publicly accessible URLs.
</Info>

<video
  controls
  className="w-full aspect-video rounded-xl"
  src="https://vkcdn.britannio.dev/vk-mcp-server.mp4"
></video>

## Setting Up MCP Integration

### Option 1: Using the Web Interface

This works if you're adding the Vibe Kanban MCP server to any [supported coding agent](/supported-coding-agents) **within** Vibe Kanban.

1. In Vibe Kanban Settings, navigate to the "MCP Servers" page
2. In the "Popular servers" section, click on the Vibe Kanban card
3. Click the `Save Settings` button

<Frame>
<img src="/images/vk-mcp-server-config.jpeg" alt="MCP Servers configuration page showing how to add Vibe Kanban MCP server" />
</Frame>

### Option 2: Manual Configuration

You can manually add the MCP server to your coding agent's configuration. The exact syntax will depend on your coding agent or MCP client.

Add the following configuration to your agent's MCP servers configuration:

```json
{
  "mcpServers": {
    "vibe_kanban": {
      "command": "npx",
      "args": ["-y", "vibe-kanban@latest", "--mcp"]
    }
  }
}
```

## Available MCP Tools

The Vibe Kanban MCP server provides the following tools for managing projects, tasks, and task execution:

### Project Operations

| Tool | Purpose | Required Parameters | Optional Parameters | Returns |
|------|---------|-------------------|-------------------|---------|
| `list_projects` | Fetch all projects | None | None | List of projects with metadata |
| `list_repos` | List repositories in a project | `project_id` | None | List of repositories with IDs |

### Context

| Tool | Purpose | Required Parameters | Optional Parameters | Returns |
|------|---------|-------------------|-------------------|---------|
| `get_context` | Get current workspace context (only available within an active workspace session) | None | None | Project, task, and workspace metadata |

### Task Management

| Tool | Purpose | Required Parameters | Optional Parameters | Returns |
|------|---------|-------------------|-------------------|---------|
| `list_tasks` | List tasks in a project | `project_id` | `status`<br/>`limit` | List of tasks with execution state |
| `create_task` | Create a new task | `project_id`<br/>`title` | `description` | Created task ID and confirmation |
| `get_task` | Get task details | `task_id` | None | Full task information |
| `update_task` | Update task details | `task_id` | `title`<br/>`description`<br/>`status` | Updated task information |
| `delete_task` | Delete a task | `task_id` | None | Deletion confirmation |

### Task Execution

| Tool | Purpose | Required Parameters | Optional Parameters | Returns |
|------|---------|-------------------|-------------------|---------|
| `start_workspace_session` | Start working on a task with a coding agent | `task_id`<br/>`executor`<br/>`repos` | `variant` | Task ID and workspace ID |

The `repos` parameter is an array of objects with:
- `repo_id`: The repository ID (UUID)
- `base_branch`: The base branch for this repository

### Supported Executors

When using `start_workspace_session`, the following executors are supported (case-insensitive, accepts hyphens or underscores):

- `claude-code` / `CLAUDE_CODE`
- `amp` / `AMP`
- `gemini` / `GEMINI`
- `codex` / `CODEX`
- `opencode` / `OPENCODE`
- `cursor_agent` / `CURSOR_AGENT`
- `qwen-code` / `QWEN_CODE`
- `copilot` / `COPILOT`
- `droid` / `DROID`

## Using the MCP Server

Once you have the MCP server configured, you can leverage it to streamline your project planning and execution workflow:

1. **Plan Your Work**: Describe a large feature or project to your MCP client
2. **Request Task Creation**: At the end of your task description, simply add "then turn this plan into tasks"
3. **Automatic Task Generation**: Your MCP client will use the Vibe Kanban MCP server to automatically create structured tasks in your project
4. **Start Task Execution**: Use `start_workspace_session` to programmatically begin work on tasks with specific coding agents

## Example Usage

### Planning and Task Creation

```
I need to build a user authentication system with the following features:
- User registration with email validation
- Login/logout functionality
- Password reset capability
- Session management
- Protected routes

Then turn this plan into tasks.
```

Your MCP client will use the `create_task` tool to break this down into individual tasks and add them to your Vibe Kanban project automatically.

### Starting Task Execution

After tasks are created, you can start work on them programmatically:

```
Start working on the user registration task using Claude Code on the main branch.
```

Your MCP client will use the `start_workspace_session` tool with parameters like:
```json
{
  "task_id": "123e4567-e89b-12d3-a456-426614174000",
  "executor": "claude-code",
  "repos": [
    {
      "repo_id": "987fcdeb-51a2-3d4e-b678-426614174001",
      "base_branch": "main"
    }
  ]
}
```

This creates a new task attempt, generates a feature branch, and starts the coding agent in an isolated environment.

### Complete Workflow Example

```
1. List all projects to find the project ID
2. List todo tasks in the project
3. Create a new task for "Add user profile page"
4. Start a task attempt for the new task using Amp on the develop branch
```

Each step uses the appropriate MCP tool (`list_projects`, `list_tasks`, `create_task`, `start_workspace_session`) to manage the complete workflow from planning to execution.

### Internal Coding Agents (Within Vibe Kanban)

A powerful workflow involves using coding agents within Vibe Kanban that are also connected to the Vibe Kanban MCP server:

1. **Create a Planning Task**: Create a task with a custom agent profile configured with a planning prompt. See [Agent Configurations](/configuration-customisation/agent-configurations) for details on creating custom profiles.
2. **Explore and Plan**: The coding agent explores the codebase and develops a comprehensive plan
3. **Generate Tasks**: Ask the coding agent to "create a series of individual tasks for this plan"
4. **Automatic Population**: The agent uses the MCP server to populate individual tasks directly in the Vibe Kanban interface

This creates a seamless workflow where high-level planning automatically generates actionable tasks in your project board.

## Installation Instructions for MCP Clients

### Raycast Example

Raycast is a popular MCP client that can connect to Vibe Kanban's MCP server. Here's how to configure it:

For complete Raycast MCP configuration details, see the [official Raycast MCP documentation](https://manual.raycast.com/model-context-protocol).

<Tabs>
<Tab title="Step 1: Open MCP Server Installer">
<Frame>
<img src="/images/vk-raycast-mcp-part-1.png" alt="Raycast MCP configuration - adding Vibe Kanban server" />
</Frame>

Configure the Vibe Kanban MCP server in Raycast by adding the server details.
</Tab>

<Tab title="Step 2: Supply Command">
<Frame>
<img src="/images/vk-raycast-mcp-part-2.png" alt="Raycast MCP configuration - server successfully added" />
</Frame>

Once configured, you'll see the Vibe Kanban MCP server listed and ready to use in Raycast.
</Tab>
</Tabs>

<Note>
Similar configuration steps apply to other MCP clients like Claude Desktop, VS Code with MCP extensions, or any custom MCP client implementations.
</Note>