🚀 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:

   bash

   Copy

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

2. Build the executable:

   On Windows:

   cmd

   Copy

   build-release.bat
   

   On Linux/macOS:

   bash

   Copy

   ./build-release.sh
   

   Manual build:

   bash

   Copy

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

⚙️ 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

  server.ts

  Copy

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

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

  server.ts

  Copy

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

• bearer: Uses Bearer token authentication

  server.ts

  Copy

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

🔧 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:

   server.ts

   Copy

   export KANBOARD_DEBUG="true"
   

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

3. Temporarily skip RBAC for testing:

   server.ts

   Copy

   export KANBOARD_SKIP_RBAC="true"
   

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

4. Manually set roles via environment:

   server.ts

   Copy

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

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

📋 Board Management

🧑‍💻 Current User Management

🔗 External Task Link Management

🔗 Internal Task Link Management

🔗 Link Management

📂 Project File Management

📝 Project Metadata Management

🔐 Project Permission Management

📝 Subtask Management

⏰ Subtask Time Tracking

🏷️ Tag Management

📂 Task File Management

📝 Task Metadata Management

⚙️ Application Management

🤖 Automatic Actions Management

👥 Group Management

👥 Group Member Management

👥 User Management

🏃 ScrumSprint Plugin API

📖 Usage Examples

Project Workflow

# Create a new project
"Create a new project called 'Mobile App Development'"

# Add tasks to the project
"Create task 'Design UI mockups' in project 'Mobile App Development'"
"Create task 'Set up development environment' in project 'Mobile App Development'"

# Get all tasks
"Get tasks for 'Mobile App Development' project"

# Move tasks between columns
"Move task 1 to 'In Progress' column"
"Move task 2 to 'Done' column"

Team Management

# Create a new team member
"Create user 'alice.smith' with password 'secure123' and email 'alice@company.com'"

# Assign user to project
"Assign user 'alice.smith' to project 'Mobile App Development' as project-member"

# Assign tasks to team members
"Assign task 1 to user 'alice.smith'"

Task Organization

# Create categories for better organization
"Create category 'Critical Bugs'"
"Create category 'Feature Requests'"

# Add comments to tasks
"Add comment 'This needs urgent attention' to task 5"

# Set deadlines
"Set due date for task 3 to 2024-01-20"

🔧 Development

Building from Source

# Clone the repository
git clone https://github.com/bivex/kanboard-mcp.git
cd kanboard-mcp

# Install dependencies
go mod download

# Build the application
go build -o kanboard-mcp .

# Run tests
go test ./...

Project Structure

kanboard-mcp/
├── main.go              # Main application entry point
├── go.mod               # Go module dependencies
├── go.sum               # Dependency checksums
├── build-release.bat    # Windows build script
├── build-release.sh     # Unix build script
├── README.md            # This file
└── LICENSE.md           # License information

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE.md file for details.