npm package: @kanbodev/mcp
Description: MCP (Model Context Protocol) server for Kanbo - AI-native project management
Author: Kanbo
Latest version: 1.2.1

# Kanbo MCP Server

[![npm version](https://img.shields.io/npm/v/@kanbodev/mcp.svg)](https://www.npmjs.com/package/@kanbodev/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

AI-native project management via [Model Context Protocol](https://modelcontextprotocol.io). Connect your AI assistant (VS Code, Cursor, Windsurf, Claude Code, Claude Desktop) to [Kanbo](https://www.kanbo.dev/) and manage tickets, projects, releases, and workflows through natural conversation.

[Try the demo](https://www.kanbo.dev/demo) | [See a live project](https://hub.kanbo.dev/dev/default)

## Quick Setup

```bash
npx @kanbodev/mcp login
```

That's it. This single command will:

1. Open your browser to sign in and select your organization
2. Store credentials locally at `~/.kanbo/config.json`
3. **Auto-register the MCP server** with detected editors (VS Code, VS Code Insiders, Cursor, Windsurf, Claude Code, Claude Desktop, Claude Code CLI)

Reload your editor and start using Kanbo tools immediately.

### Already logged in? Register manually

If you authenticated previously and need to register with a new editor:

```bash
npx @kanbodev/mcp install
```

### Windows note

On Windows, `npx` can cause stdio piping issues with some MCP hosts. The `install` command automatically uses `node` with a direct path instead. If you're setting up manually on Windows, use:

```json
{
  "mcpServers": {
    "kanbodev": {
      "type": "stdio",
      "command": "node",
      "args": ["C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\@kanbodev\\mcp\\dist\\index.js"]
    }
  }
}
```

Replace `<you>` with your Windows username, or run `npm root -g` to find the correct path.

### Manual setup

If auto-registration doesn't detect your editor, add the config manually:

**VS Code / VS Code Insiders / Cursor** — add to `mcp.json`:

```json
{
  "servers": {
    "kanbodev": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kanbodev/mcp"]
    }
  }
}
```

**Claude Desktop / Windsurf / Claude Code** — add to config with `mcpServers` key:

```json
{
  "mcpServers": {
    "kanbodev": {
      "type": "stdio",
      "command": "npx",
      "args": ["@kanbodev/mcp"]
    }
  }
}
```

**Claude Code CLI:**

```bash
claude mcp add kanbodev -- npx @kanbodev/mcp
```

<details>
<summary>Config file locations</summary>

| Editor | Config Path |
|--------|-------------|
| VS Code | `~/Library/Application Support/Code/User/mcp.json` (macOS) / `%APPDATA%\Code\User\mcp.json` (Windows) |
| VS Code Insiders | `~/Library/Application Support/Code - Insiders/User/mcp.json` (macOS) / `%APPDATA%\Code - Insiders\User\mcp.json` (Windows) |
| Cursor | `~/.cursor/mcp.json` |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
| Claude Code | `~/.claude/settings.json` |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) |

</details>

### Manual API key setup

If you prefer environment variables over the login flow:

1. Go to your Kanbo dashboard → **Settings → API Keys**
2. Create a new key and copy the token
3. Add `"env": { "KANBO_API_KEY": "kanbo_pat_..." }` to your editor's MCP config

### Environment variables

| Variable | Description | Default |
|----------|-------------|---------|
| `KANBO_API_KEY` | Personal Access Token (overrides config file) | from `~/.kanbo/config.json` |
| `KANBO_API_URL` | API server URL | `https://api.kanbo.dev` |
| `KANBO_WEB_URL` | Web app URL for login | `https://kanbo.dev` |

---

## User Guide

Once connected, you interact with Kanbo through natural language. Here's what you can do and how to ask for it.

### Getting oriented

Start by asking your AI assistant to discover your workspace:

> "What Kanbo organizations do I have access to?"
>
> "List all my projects"
>
> "Show me the project stats for the frontend project"

The assistant will call `list_organizations`, `list_projects`, and `get_project_stats` behind the scenes.

### Creating a ticket

You can create tickets with as much or as little detail as you want:

> "Create a ticket in the Frontend project called 'Fix login button not responding on mobile'"

The assistant will look up your project, check for similar/related tickets, find available statuses, priorities, and sizes, then create the ticket with acceptance criteria. You can also be more specific:

> "Create a high-priority bug in Frontend: 'Payment form crashes on Safari'. Assign it to me and put it in the To Do column."

For AI-assisted creation:

> "I need a ticket about improving the search performance. Can you polish the title, generate a description, and suggest the right priority and type?"

This uses the AI tools (`polish_title`, `generate_description`, `suggest_attributes`) to craft a well-defined ticket before creating it.

### Acceptance criteria

Every ticket includes structured acceptance criteria — specific, testable conditions that define "done":

> "Add acceptance criteria to PROJ-123: users can export in CSV and JSON, progress shows for large exports, and errors display a retry option"
>
> "Show me the acceptance criteria for PROJ-45"

The assistant uses Given/When/Then format and includes both happy-path and edge-case criteria automatically.

### Related tickets and subtasks

The assistant checks for duplicates and related work before creating tickets, and supports parent-child relationships for breaking down work:

> "Create a subtask under PROJ-100: 'Write unit tests for auth module'"
>
> "Show me the child tickets of PROJ-100"
>
> "Find tickets similar to 'password reset not working'"

### Finding and viewing tickets

> "Show me all my assigned tickets"
>
> "What tickets are in the backlog for the API project?"
>
> "Get ticket PROJ-123"
>
> "What tickets are overdue?"
>
> "Show me tickets due in the next 3 days"
>
> "Search for tickets related to 'authentication'"

### Moving tickets through the workflow

> "Move PROJ-123 to In Progress"
>
> "Complete ticket PROJ-45"
>
> "Move all the QA-approved tickets to Done"

The assistant respects your workflow transition rules — it checks which status transitions are allowed before moving tickets.

### Managing the backlog

> "Move PROJ-78 to the backlog"
>
> "Pull PROJ-78 back to the board and put it in To Do"
>
> "Show me the backlog for the mobile project"
>
> "Restore the deleted ticket PROJ-99 and put it in the backlog"

### Comments and collaboration

> "Add a comment to PROJ-123: 'Tested on Chrome and Firefox, both working now'"
>
> "Show me the comments on PROJ-45"
>
> "What are my unread notifications?"
>
> "Mark all notifications as read"

### Tags and labels

> "List all tags in the Frontend project"
>
> "Create a tag called 'performance' with color orange"
>
> "Tag PROJ-123 with 'performance' and 'backend'"

### Release management

> "Create a release called 'v2.1.0' with target date March 15"
>
> "Add tickets PROJ-10, PROJ-11, and PROJ-12 to the v2.1.0 release"
>
> "Show me the burndown for v2.1.0"
>
> "Ship the v2.1.0 release"

### Bulk operations

> "Complete all tickets in the Done column"
>
> "Assign all unassigned tickets in Sprint 5 to me"
>
> "Move these 10 tickets to the QA status"

Batch operations work on up to 50 tickets at once.

### AI features

> "Find tickets similar to 'user can't reset password'"
>
> "Fix the grammar in this ticket description: ..."
>
> "Make this description clearer: ..."
>
> "Check if this title is clear enough: 'fix thing'"
>
> "Create a ticket from my notes: users need to be able to export reports as PDF, it should respect filters, and show a progress bar for large exports"

The last example passes your raw notes directly to `generate_description` — the AI organizes, structures, and expands them into a full ticket description rather than generating from scratch.

### Analytics and reporting

> "Show me the team analytics for the Frontend project"
>
> "What's the average cycle time for tickets?"
>
> "Show the ticket distribution by priority and type"

### Checking usage

> "How many MCP requests have I used today?"
>
> "What's my AI usage this week?"

---

## Example Workflows

### Daily standup

> "Show me my tickets, any overdue items, and what's due this week"

### Sprint planning

> "Create a release called 'Sprint 12' with target date Feb 28. Then show me the backlog so I can pick tickets to include."

### Triage new bugs

> "Show me all tickets tagged 'bug' that don't have an assignee. For each one, suggest a priority and size."

### End of sprint

> "Show me all tickets in Sprint 11. Complete the ones in the Done column, and move any incomplete ones to the backlog."

---

## Available Tools (125)

| Category | Count | Key Tools |
|----------|-------|-----------|
| **Tickets** | 24 | `create_ticket`, `update_ticket`, `move_ticket`, `complete_ticket`, `get_my_tickets`, `get_overdue_tickets` |
| **Projects** | 11 | `list_projects`, `create_project`, `get_project_stats`, `get_project_summaries` |
| **Releases** | 17 | `create_release`, `assign_tickets_to_release`, `mark_release_shipped`, `get_release_burndown`, `get_release_history` |
| **Workflow** | 8 | `list_statuses`, `get_available_transitions`, `create_status`, `create_transition` |
| **Tags** | 8 | `list_tags`, `create_tag`, `add_tag_to_ticket`, `set_ticket_tags` |
| **AI** | 8 | `polish_title`, `generate_description`, `find_similar_tickets`, `suggest_attributes` |
| **Organization** | 6 | `list_organizations`, `set_organization`, `list_organization_members` |
| **Comments** | 5 | `add_comment`, `list_comments`, `update_comment` |
| **Notifications** | 5 | `list_notifications`, `get_unread_count`, `mark_all_notifications_read` |
| **Priorities** | 5 | `list_priorities`, `create_priority`, `update_priority` |
| **Sizes** | 5 | `list_sizes`, `create_size`, `update_size` |
| **Ticket Types** | 5 | `list_ticket_types`, `create_ticket_type` |
| **Members** | 4 | `add_project_member`, `remove_project_member`, `update_project_member_role` |
| **Batch** | 3 | `batch_move_tickets`, `batch_complete_tickets`, `batch_assign_tickets` |
| **Analytics** | 3 | `get_member_analytics`, `get_cycle_time_analytics`, `get_distribution_analytics` |
| **History** | 2 | `get_ticket_history`, `get_project_activity` |
| **Watchers** | 2 | `get_watch_status`, `toggle_watch` |
| **Usage** | 2 | `get_mcp_usage`, `get_ai_usage` |
| **Attachments** | 1 | `list_attachments` |
| **Help** | 1 | `get_help` |

---

## CLI Commands

```bash
npx @kanbodev/mcp login      # Authenticate + auto-register MCP server
npx @kanbodev/mcp install    # Register MCP server with detected editors
npx @kanbodev/mcp uninstall  # Remove MCP server from all editors
npx @kanbodev/mcp whoami     # Check auth status
npx @kanbodev/mcp logout     # Remove credentials
npx @kanbodev/mcp help       # Show help
npx @kanbodev/mcp version    # Show version
```

## Links

- [Kanbo Website](https://www.kanbo.dev/)
- [Interactive Demo](https://www.kanbo.dev/demo)
- [Public Project Hub](https://hub.kanbo.dev/dev/default)
- [npm Package](https://www.npmjs.com/package/@kanbodev/mcp)

## License

MIT