Vibe Kanban MCP Server

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

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

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.

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 within Vibe Kanban.

In Vibe Kanban Settings, navigate to the “MCP Servers” page
In the “Popular servers” section, click on the Vibe Kanban card
Click the Save Settings button

MCP Servers configuration page showing how to add Vibe Kanban MCP server

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:

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

--mcp launches the local MCP stdio server. Any additional arguments after --mcp are passed through to the vibe-kanban-mcp binary.

Available MCP Tools

The Vibe Kanban MCP server provides tools for managing organisations, projects, issues, workspaces, and task execution.

Many tools accept an optional project_id or organization_id parameter. When running inside a workspace linked to a remote project, these are inferred automatically from context and can be omitted. The exception is list_projects, which always requires an explicit organization_id.

Context

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

Organisation Operations

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`list_organizations`	List all available organisations	None	None	List of organisations with IDs, names, and slugs
`list_org_members`	List members of an organisation	None	`organization_id`	List of members with user IDs, roles, and profile info

Project Operations

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`list_projects`	List projects in an organisation	`organization_id`	None	List of projects with IDs and names

Issue Management

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`list_issues`	List issues in a project	None	`project_id` `status` `priority` `search` `simple_id` `parent_issue_id` `assignee_user_id` `tag_id` `tag_name` `limit` `offset`	Paginated list of issues with PR info
`create_issue`	Create a new issue	`title`	`project_id` `description` `priority` `parent_issue_id`	Created issue ID
`get_issue`	Get detailed issue information	`issue_id`	None	Full issue details with tags, relationships, sub-issues, and PRs
`update_issue`	Update an existing issue	`issue_id`	`title` `description` `status` `priority` `parent_issue_id`	Updated issue details
`delete_issue`	Delete an issue	`issue_id`	None	Deletion confirmation
`list_issue_priorities`	List allowed priority values	None	None	List of priorities: urgent, high, medium, low

For update_issue, the parent_issue_id field supports three states: omit it entirely to leave the parent unchanged, pass null to un-nest the issue from its parent, or pass a UUID to set a new parent.

Issue Assignees

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`list_issue_assignees`	List assignees for an issue	`issue_id`	None	List of assignees with user IDs
`assign_issue`	Assign a user to an issue	`issue_id` `user_id`	None	Issue assignee ID
`unassign_issue`	Remove an assignee from an issue	`issue_assignee_id`	None	Unassignment confirmation

Issue Tags

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`list_tags`	List tags for a project	None	`project_id`	List of tags with IDs, names, and colours
`list_issue_tags`	List tags attached to an issue	`issue_id`	None	List of issue-tag relations
`add_issue_tag`	Attach a tag to an issue	`issue_id` `tag_id`	None	Issue-tag relation ID
`remove_issue_tag`	Remove a tag from an issue	`issue_tag_id`	None	Removal confirmation

Issue Relationships

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`create_issue_relationship`	Create a relationship between two issues	`issue_id` `related_issue_id` `relationship_type`	None	Relationship ID
`delete_issue_relationship`	Delete a relationship between issues	`relationship_id`	None	Deletion confirmation

Supported relationship types: blocking, related, has_duplicate.

Repository Management

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`list_repos`	List all repositories	None	None	List of repositories with IDs and names
`get_repo`	Get repository details including scripts	`repo_id`	None	Repository info with setup, cleanup, and dev server scripts
`update_setup_script`	Update a repository’s setup script	`repo_id` `script`	None	Update confirmation
`update_cleanup_script`	Update a repository’s cleanup script	`repo_id` `script`	None	Update confirmation
`update_dev_server_script`	Update a repository’s dev server script	`repo_id` `script`	None	Update confirmation

Workspace Management

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`list_workspaces`	List local workspaces	None	`archived` `pinned` `branch` `name_search` `limit` `offset`	Paginated list of workspaces
`update_workspace`	Update a workspace’s properties	None	`workspace_id` `archived` `pinned` `name`	Updated workspace details
`delete_workspace`	Delete a local workspace	None	`workspace_id` `delete_remote` `delete_branches`	Deletion confirmation
`link_workspace_issue`	Link a workspace to a remote issue	`workspace_id` `issue_id`	None	Link confirmation

Workspace Sessions

Tool	Purpose	Required Parameters	Optional Parameters	Returns
`start_workspace`	Create a workspace and start its first coding-agent session	`name` `executor` `repositories`	`prompt` `variant` `issue_id`	Workspace ID
`create_session`	Create a session in an existing workspace	None	`workspace_id` `executor`	Session summary
`list_sessions`	List sessions for a workspace	None	`workspace_id`	Session list
`run_session_prompt`	Run a coding-agent prompt inside an existing session	`session_id` `prompt`	None	Execution details
`get_execution`	Inspect execution status and final message	`execution_id`	None	Execution details

The repositories parameter is an array of objects with:

repo_id: The repository ID (UUID)
branch: The branch for this repository

When issue_id is provided, the workspace is automatically linked to the remote issue. If prompt is omitted, the linked issue’s title and description are used as the workspace prompt.

Supported Executors

When using start_workspace, 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:

Plan Your Work: Describe a large feature or project to your MCP client
Request Issue Creation: At the end of your description, simply add “then turn this plan into issues”
Automatic Issue Generation: Your MCP client will use the Vibe Kanban MCP server to automatically create structured issues in your project
Start Workspaces: Use start_workspace to programmatically begin work on issues with specific coding agents

Example Usage

Planning and Issue 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 issues.

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

Starting a Workspace Session

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

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

Your MCP client will use the start_workspace tool with parameters like:

{
  "name": "User registration with email validation",
  "executor": "claude-code",
  "repositories": [
    {
      "repo_id": "987fcdeb-51a2-3d4e-b678-426614174001",
      "branch": "main"
    }
  ],
  "issue_id": "123e4567-e89b-12d3-a456-426614174000"
}

This creates a new workspace, links it to the issue, generates a feature branch, and starts the coding agent in an isolated environment.

Complete Workflow Example

List organisations to find the organisation ID
List projects in the organisation to find the project ID
List issues in the project filtered by status
Create a new issue for "Add user profile page"
Assign a team member to the issue
Start a workspace session for the issue using Amp on the develop branch

Each step uses the appropriate MCP tool (list_organizations, list_projects, list_issues, create_issue, assign_issue, start_workspace) 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:

Create a Planning Issue: Create an issue with a custom agent profile configured with a planning prompt. See Agent Configurations for details on creating custom profiles.
Explore and Plan: The coding agent explores the codebase and develops a comprehensive plan
Generate Issues: Ask the coding agent to “create a series of individual issues for this plan”
Automatic Population: The agent uses the MCP server to populate individual issues directly in the Vibe Kanban interface

This creates a seamless workflow where high-level planning automatically generates actionable issues 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.

Step 1: Open MCP Server Installer
Step 2: Supply Command

Raycast MCP configuration - adding Vibe Kanban server

Configure the Vibe Kanban MCP server in Raycast by adding the server details.

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

​Setting Up MCP Integration

​Option 1: Using the Web Interface

​Option 2: Manual Configuration

​Available MCP Tools

​Context

​Organisation Operations

​Project Operations

​Issue Management

​Issue Assignees

​Issue Tags

​Issue Relationships

​Repository Management

​Workspace Management

​Workspace Sessions

​Supported Executors

​Using the MCP Server

​Example Usage

​Planning and Issue Creation

​Starting a Workspace Session

​Complete Workflow Example

​Internal Coding Agents (Within Vibe Kanban)

​Installation Instructions for MCP Clients

​Raycast Example

Setting Up MCP Integration

Option 1: Using the Web Interface

Option 2: Manual Configuration

Available MCP Tools

Context

Organisation Operations

Project Operations

Issue Management

Issue Assignees

Issue Tags

Issue Relationships

Repository Management

Workspace Management

Workspace Sessions

Supported Executors

Using the MCP Server

Example Usage

Planning and Issue Creation

Starting a Workspace Session

Complete Workflow Example

Internal Coding Agents (Within Vibe Kanban)

Installation Instructions for MCP Clients

Raycast Example