Kanban Board MCP Server

Model Context Protocol server for interacting with the Kanban Board project management system.

Overview

This MCP server provides Claude with direct access to the Kanban board API, enabling automated project and task management through conversation.

Installation

cd /data/appdata/binhex-code-server/home/.claude/kanban-mcp
npm install
npm run build

Configuration

Add to your mcp.json:

{
  "mcpServers": {
    "kanban": {
      "type": "stdio",
      "command": "node",
      "args": ["/config/home/.claude/kanban-mcp/dist/index.js"],
      "env": {
        "KANBAN_URL": "http://192.168.0.20:3010",
        "KANBAN_WRITE_ENABLED": "true"
      }
    }
  }
}

Environment Variables

• KANBAN_URL: Base URL of the Kanban API (default: http://localhost:3010)
• KANBAN_WRITE_ENABLED: Enable write operations (true or false, default: false)

Available Tools

Projects (Read)

• list_projects: List all projects with statistics
• get_project: Get detailed information about a specific project

Projects (Write)

• create_project: Create a new project
  • Required: name
  • Optional: color, repo
• update_project: Update project properties
  • Required: projectId
  • Optional: name, description, color, repo, theme, status, url, umamiId
• delete_project: Delete a project
  • Required: projectId

Cards (Read)

• list_cards: List cards with optional filters
  • Optional: projectId, columnId
• get_card: Get detailed card information
  • Required: cardId
• get_card_history: Get change history for a card
  • Required: cardId

Cards (Write)

• create_card: Create a new task/card
  • Required: title, projectId
  • Optional: description, columnId, priority, type, labels, storyPoints, assignee, reporter, dueDate
• update_card: Update card properties
  • Required: cardId
  • Optional: title, description, priority, type, labels, storyPoints, assignee, dueDate
• move_card: Move card to a different column
  • Required: cardId, columnId
  • Optional: pauseReason (required if moving to paused column)
• delete_card: Delete a card
  • Required: cardId
• update_checklist: Toggle checklist items
  • Required: cardId, item
  • Optional: value
  • Items: codeComplete, testsWritten, codeReviewed, documentationUpdated, rollbackProcedure

Pipeline (4 tools)

• list_pipeline_stages: List all pipeline stages with descriptions
  • Returns: Stage numbers (1-7) with names and descriptions
  • Use this first to understand which stage to update
• get_card_pipeline_status: Get current pipeline status with intelligent suggestions
  • Required: cardId
  • Returns: Current stage, status, errors, retry count, and suggested next stage
  • Recommended: Use this before updating pipeline to know what to do next
• update_pipeline_stage: Update CI/CD pipeline stage
  • Required: cardId, stage (1-7), status (running/passed/failed)
  • Optional: error (required if status is failed)
• clear_pipeline_stage: Clear/reset pipeline stage
  • Required: cardId

Board & Statistics

• list_columns: List all Kanban board columns
• get_statistics: Get project statistics and metrics
  • Optional: projectId, timeRange (1month/3months/6months/12months)
• get_board: Get entire board (projects + columns + cards)

Column IDs

• backlog: Ideas and raw tasks
• discovered: Tasks refined with acceptance criteria
• in-development: Active development
• paused: Blocked tasks (requires pause reason)
• verify-release: Verification and release
• done: Completed tasks
• cancelled: Archived tasks

Card Types

• feature: New functionality
• bug: Bug fixes
• documentation: Documentation updates
• other: Other work items

Priority Levels

• low: Low priority
• medium: Medium priority (default)
• high: High priority

Architecture

┌─────────────────┐
│  Claude/Skills  │
└────────┬────────┘
         │ MCP Protocol (JSON-RPC 2.0)
         │ stdio transport
┌────────▼────────┐
│  Kanban MCP     │
│    Server       │
└────────┬────────┘
         │ REST API (HTTP)
┌────────▼────────┐
│  Kanban Board   │
│   Backend       │
│  (Node.js)      │
└────────┬────────┘
         │ PostgreSQL
┌────────▼────────┐
│  Urd Database   │
│  (PostgreSQL)   │
└─────────────────┘

Usage Examples

List all projects

// Claude will call: list_projects
// Returns: Array of projects with stats

Create a new card

// Claude will call: create_card
// Arguments: {
//   title: "Implement user authentication",
//   projectId: "my-project",
//   type: "feature",
//   priority: "high",
//   storyPoints: 5
// }

Move card through workflow

// Claude will call: move_card
// Arguments: {
//   cardId: "card-abc123",
//   columnId: "in-development"
// }

Check pipeline status and update intelligently

// Step 1: Get current status and suggestions
// Claude will call: get_card_pipeline_status
// Arguments: { cardId: "card-abc123" }
// Returns: {
//   currentPipeline: { stage: 2, stageName: "Implementation", status: "passed" },
//   suggestion: "Stage 2 passed. Next: stage 3 (Security Audit)",
//   nextStage: { stage: 3, name: "Security Audit", description: "..." }
// }

// Step 2: Update to next stage based on suggestion
// Claude will call: update_pipeline_stage
// Arguments: {
//   cardId: "card-abc123",
//   stage: 3,  // From suggestion
//   status: "running"
// }

List all pipeline stages

// Claude will call: list_pipeline_stages
// Returns: [
//   { stage: 1, name: "Preparation", description: "Load card, create branch" },
//   { stage: 2, name: "Implementation", description: "Apply dev conventions" },
//   { stage: 3, name: "Security Audit", description: "Check OWASP Top 10" },
//   { stage: 4, name: "Quality Assurance", description: "Validate requirements" },
//   { stage: 5, name: "Deployment", description: "Push to GitHub, trigger build" },
//   { stage: 6, name: "Verification", description: "Automated tests" },
//   { stage: 7, name: "Complete", description: "All checks passed" }
// ]

Development

Build

npm run build

Watch mode

npm run watch

Testing

# Test tool listing
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  KANBAN_URL="http://localhost:3010" \
  KANBAN_WRITE_ENABLED="true" \
  node dist/index.js

Safety Features

• Write Protection: Set KANBAN_WRITE_ENABLED=false to make server read-only
• Error Handling: All API errors are caught and returned as MCP errors
• Input Validation: Zod schema validation on all tool inputs

Dependencies

• @modelcontextprotocol/sdk: Official MCP SDK
• zod: Runtime type validation
• typescript: Type safety during development

Version

Current version: 0.2.0

Changelog

v0.2.0 - Pipeline Intelligence

• Added list_pipeline_stages - List all stages with descriptions
• Added get_card_pipeline_status - Get current status with intelligent next-step suggestions
• Agents can now understand pipeline stages without hardcoding stage numbers

v0.1.0 - Initial Release

• 18 basic tools for project and card management

License

MIT