Kanboard

🚀 Kanboard MCP Server

Model Context Protocol (MCP) Server for Kanboard Integration

A powerful Go-based MCP server that enables seamless integration between AI assistants (like Claude Desktop, Cursor) and Kanboard project management system. Manage your Kanboard projects, tasks, users, and workflows directly through natural language commands.

⚠️ Warning: To avoid issues like these:

We recommend using mcpproxy as a proxy solution.

📋 Table of Contents

• ✨ Features
• 🚀 Quick Start
• ⚙️ Configuration
• 🛠️ Available Tools
• 📖 Usage Examples
• 🔧 Development
• 📄 License

✨ Features

• 🔗 Seamless Kanboard Integration - Direct API communication with Kanboard
• 🤖 Natural Language Processing - Use plain English to manage your projects
• 📊 Complete Project Management - Handle projects, tasks, users, columns, and more
• 🔐 Secure Authentication - Support for both API key and username/password auth
• ⚡ High Performance - Built with Go for optimal performance
• 🎯 MCP Standard - Compatible with all MCP clients

🚀 Quick Start

Prerequisites

• Go 1.21 or higher
• Kanboard instance with API access
• MCP-compatible client (Cursor, Claude Desktop, etc.)

Installation

1. Clone the repository:

   git clone https://github.com/bivex/kanboard-mcp.git
   cd kanboard-mcp

   Copy to clipboard

2. Build the executable:

   On Windows:

   build-release.bat

   Copy to clipboard

   On Linux/macOS:

   ./build-release.sh

   Copy to clipboard

   Manual build:

   go build -ldflags="-s -w" -o kanboard-mcp .

   Copy to clipboard

⚙️ Configuration

1. Environment Variables

Set up your Kanboard credentials and RBAC permissions using environment variables:

Required Credentials:

export KANBOARD_API_ENDPOINT="https://your-kanboard-url/jsonrpc.php"
export KANBOARD_API_KEY="your-kanboard-api-key"
export KANBOARD_USERNAME="your-kanboard-username"
export KANBOARD_PASSWORD="your-kanboard-password"

RBAC Configuration (Optional):

Configure user roles for proper access control. If not set, the system will try to get roles from Kanboard API, falling back to app-user role.

# Application-level roles (comma-separated)
# If not set, roles are automatically retrieved from Kanboard API
export KANBOARD_USER_APP_ROLES="app-manager"

# Project-specific roles (format: "project_id:role,project_id:role")
# If not set, project roles are automatically retrieved from Kanboard API
export KANBOARD_USER_PROJECT_ROLES="1:project-manager,2:project-member"

# Debug mode - shows detailed permission checking logs
export KANBOARD_DEBUG="true"

# Skip RBAC checks for debugging (use with caution!)
export KANBOARD_SKIP_RBAC="false"

Available Application Roles:

• app-admin - Full system administrator access
• app-manager - Can create projects and manage users
• app-user - Basic user access (default)

Available Project Roles:

• project-manager - Full project management access
• project-member - Can create/modify tasks and comments
• project-viewer - Read-only access to project

🔐 Authentication Methods:

Kanboard supports different authentication methods via KANBOARD_AUTH_METHOD:

• global_token (default): Uses global API token with jsonrpc:<token> format

  export KANBOARD_API_KEY="5348e6b4846fe09fd1670e922bc13e086f0827d7a66e45815cd7c3a7f67b"
  export KANBOARD_AUTH_METHOD="global_token"  # or omit (default)

  Copy to clipboard

• user_token: Uses user-specific API token with <username>:<token> format

  export KANBOARD_USERNAME="admin"
  export KANBOARD_API_KEY="81820aeb3454985b0ac12166225f1f072f523175a752541c8670cf44a032d"
  export KANBOARD_AUTH_METHOD="user_token"

  Copy to clipboard

• bearer: Uses Bearer token authentication

  export KANBOARD_API_KEY="your-token-here"
  export KANBOARD_AUTH_METHOD="bearer"

  Copy to clipboard

🔧 Troubleshooting RBAC Issues:

If you're getting "access denied" errors:

1. Check your user role in Kanboard:

   • Go to Kanboard web interface
   • Check your user profile/role settings
   • Ensure you have appropriate permissions

2. Enable debug logging:

   export KANBOARD_DEBUG="true"

   Copy to clipboard

   This will show your current roles and permission checks in the console.

3. Temporarily skip RBAC for testing:

   export KANBOARD_SKIP_RBAC="true"

   Copy to clipboard

   ⚠️ Warning: Only use for debugging! Disables all permission checks.

4. Manually set roles via environment:

   export KANBOARD_USER_APP_ROLES="app-admin"
   export KANBOARD_USER_PROJECT_ROLES="27:project-manager"

   Copy to clipboard

2. MCP Client Configuration

Create the MCP configuration file for your client:

Location:

• Windows: C:\Users\YOUR_USERNAME\AppData\Roaming\Cursor\.cursor\mcp_config.json
• Linux/macOS: ~/.cursor/mcp_config.json

Configuration:

{
  "mcpServers": {
    "kanboard-mcp-server": {
      "command": "/path/to/your/kanboard-mcp",
      "args": [],
      "env": {
        "KANBOARD_API_ENDPOINT": "https://your-kanboard-url/jsonrpc.php",
        "KANBOARD_API_KEY": "your-kanboard-api-key",
        "KANBOARD_USERNAME": "your-kanboard-username",
        "KANBOARD_PASSWORD": "your-kanboard-password",
        "KANBOARD_USER_APP_ROLES": "app-manager",
        "KANBOARD_USER_PROJECT_ROLES": "1:project-manager"
      }
    }
  }
}

3. Restart Your Client

After saving the configuration, restart your MCP client (Cursor, Claude Desktop, etc.) for changes to take effect.

🛠️ Available Tools

📁 Project Management

📝 Task Management

💬 Comment Management

🏗️ Column Management

🏷️ Category Management

🏊 Swimlane Management

…