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
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.
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 |
| 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 |
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 |
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_CODEamp / AMPgemini / GEMINIcodex / CODEXopencode / OPENCODEcursor_agent / CURSOR_AGENTqwen-code / QWEN_CODEcopilot / COPILOTdroid / 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.
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.
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"
}
Complete Workflow Example
1. List organisations to find the organisation ID
2. List projects in the organisation to find the project ID
3. List issues in the project filtered by status
4. Create a new issue for "Add user profile page"
5. Assign a team member to the issue
6. Start a workspace session for the issue using Amp on the develop branch
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.
Configure the Vibe Kanban MCP server in Raycast by adding the server details. Once configured, you’ll see the Vibe Kanban MCP server listed and ready to use in Raycast. Similar configuration steps apply to other MCP clients like Claude Desktop, VS Code with MCP extensions, or any custom MCP client implementations.
