businessmap-mcp

hivemq/businessmap-mcp

3.3

If you are the rightful owner of businessmap-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Businessmap MCP Server is a Go-based server that provides access to Businessmap cards, allowing users to read card information and add comments.

Tools
2
Resources
0
Prompts
0

Businessmap MCP Server

Go Version License MCP Protocol

A Go-based Model Context Protocol (MCP) server that provides comprehensive access to Businessmap (formerly Kanbanize) cards including reading card information and adding comments.

Features

  • šŸŽÆ Two MCP Tools:
    • read_card - Comprehensive card information retrieval
    • add_card_comment - Add comments to existing cards
  • šŸ“Š Structured Data: Returns clean JSON with title, description, subtasks, and comments
  • āœļø Card Interaction: Add comments to cards directly through the API
  • šŸ” Secure Authentication: API key and base URL configuration via environment variables
  • šŸ”— Direct API Integration: Uses official Businessmap API v2 endpoints
  • āš” Lightweight: Minimal dependencies and fast response times
  • šŸš€ Native Performance: Direct Go binary execution without containers

Prerequisites

  • Go 1.25 or later
  • Kanbanize/Businessmap account with API access

Quick Start

1. Configuration

Copy the environment template and configure your Kanbanize credentials:

cp .env.example .env

Edit .env and set your values:

KANBANIZE_API_KEY=your_actual_api_key
KANBANIZE_BASE_URL=https://your-subdomain.kanbanize.com

2. Getting Your API Key

  1. Log into your Kanbanize/Businessmap account
  2. Click on your user dropdown menu (top right)
  3. Select "API"
  4. Copy your API key

3. Build and Run

# Install dependencies
go mod download

# Build the server
go build -o businessmap-mcp

# Run the server
./businessmap-mcp

Claude Code Integration

This MCP server is designed to work seamlessly with Claude Code. Follow these steps to integrate:

1. Install and Build

# Clone the repository
git clone https://github.com/hivemq/businessmap-mcp.git
cd businessmap-mcp

# Install dependencies
go mod download

# Build the server
go build -o businessmap-mcp

2. Configure Claude Code

Add the MCP server to your Claude Code configuration. Create or edit your Claude Code configuration file:

For Claude Code CLI (~/.claude/mcp_servers.json):

{
  "mcpServers": {
    "businessmap": {
      "command": "/path/to/businessmap-mcp/businessmap-mcp",
      "env": {
        "KANBANIZE_API_KEY": "your_api_key_here",
        "KANBANIZE_BASE_URL": "https://your-subdomain.kanbanize.com"
      }
    }
  }
}

For Claude Desktop (configuration file location varies by OS):

{
  "mcpServers": {
    "businessmap": {
      "command": "/absolute/path/to/businessmap-mcp",
      "env": {
        "KANBANIZE_API_KEY": "your_api_key_here", 
        "KANBANIZE_BASE_URL": "https://your-subdomain.kanbanize.com"
      }
    }
  }
}

3. Environment Variables (Alternative)

Instead of putting credentials in the config file, you can use a .env file:

# In the businessmap-mcp directory
cp .env.example .env
# Edit .env with your credentials

Then update the Claude Code config to use the working directory:

{
  "mcpServers": {
    "businessmap": {
      "command": "/path/to/businessmap-mcp/businessmap-mcp",
      "cwd": "/path/to/businessmap-mcp"
    }
  }
}

4. Restart Claude Code

After updating the configuration, restart Claude Code to load the new MCP server.

5. Using the Tools

Once integrated, you can use the tools in Claude Code:

Reading card information:

Please read the details of Businessmap card 12345

Reading card from URL (supports various URL formats):

Please read the details from https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345
Please read the details from https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/
Please read the details from https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/details/
Please read the details from https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/comments/

Adding comments to cards:

Please add a comment "Work completed successfully" to Businessmap card 12345

Adding comments using URL (supports various URL formats):

Please add a comment "Task completed" to https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345
Please add a comment "Task completed" to https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/
Please add a comment "Task completed" to https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/details/
Please add a comment "Task completed" to https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/comments/

Claude will automatically use the MCP server to fetch comprehensive card information or add comments as requested.

Usage

The MCP server communicates via stdin/stdout using the JSON-RPC protocol. It provides two tools:

read_card

Description: Read comprehensive card information including title, description, subtasks, and comments

Parameters:

  • card_id (string, required): The ID of the Kanbanize card to read or full card URL

Example Response:

{
  "title": "Card Title",
  "description": "Card description text",
  "subtasks": [
    {
      "id": "123",
      "title": "Subtask title",
      "description": "Subtask description",
      "completed": false
    }
  ],
  "comments": [
    {
      "id": "456",
      "text": "Comment text",
      "author": "Author Name",
      "created_at": "2023-12-01T10:00:00Z"
    }
  ]
}

add_card_comment

Description: Add a comment to a card

Parameters:

  • card_id (string, required): The ID of the Kanbanize card to add comment to or full card URL
  • comment_text (string, required): The text of the comment to add

Example Response:

"Comment added successfully"

Testing

Prerequisites for Testing

  1. Kanbanize Account: Active Kanbanize/Businessmap account with API access
  2. API Key: Generated from your account settings (User menu ā†’ API)
  3. Card ID: Valid card ID from your Kanbanize board to test with
  4. Environment Setup: Configured .env file with your credentials

Quick Test

  1. Setup Environment:

    cp .env.example .env
# Edit .env with your actual API key and base URL

  2. Build and Test:

    # Build the server
go build -o businessmap-mcp

# Test read_card only (replace 12345 with your actual card ID)
./tests/test_mcp.sh 12345

# Test with full URL (various formats supported)
./tests/test_mcp.sh "https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345"
./tests/test_mcp.sh "https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/"
./tests/test_mcp.sh "https://yourcompany.kanbanize.com/ctrl_board/123/cards/12345/details/"

# Test both read_card and add_card_comment tools
./tests/test_mcp.sh 12345 "Test comment from MCP server"

Testing Options

Option 1: Shell Script (Recommended)
# Test read_card only with card ID
./tests/test_mcp.sh YOUR_CARD_ID

# Test read_card with full URL (various formats supported)
./tests/test_mcp.sh "https://yourcompany.kanbanize.com/ctrl_board/123/cards/YOUR_CARD_ID"
./tests/test_mcp.sh "https://yourcompany.kanbanize.com/ctrl_board/123/cards/YOUR_CARD_ID/"
./tests/test_mcp.sh "https://yourcompany.kanbanize.com/ctrl_board/123/cards/YOUR_CARD_ID/details/"
./tests/test_mcp.sh "https://yourcompany.kanbanize.com/ctrl_board/123/cards/YOUR_CARD_ID/comments/"

# Test both tools
./tests/test_mcp.sh YOUR_CARD_ID "Your test comment"
Option 2: Interactive Python Script
# Test read_card only with card ID
python3 tests/test_interactive.py YOUR_CARD_ID

# Test read_card with full URL  
python3 tests/test_interactive.py "https://yourcompany.kanbanize.com/ctrl_board/123/cards/YOUR_CARD_ID/"

# Test both tools
python3 tests/test_interactive.py YOUR_CARD_ID "Your test comment"
Option 3: Manual JSON-RPC Testing
# Replace YOUR_CARD_ID in the test file (tests both tools)
sed 's/REPLACE_WITH_CARD_ID/YOUR_CARD_ID/g' tests/test_messages.jsonl | ./businessmap-mcp

# Or test with URL (escape slashes properly)
sed 's|REPLACE_WITH_CARD_ID|https://yourcompany.kanbanize.com/ctrl_board/123/cards/YOUR_CARD_ID/|g' tests/test_messages.jsonl | ./businessmap-mcp

Expected Output

The server should return a clean JSON response like:

{
  "title": "Example Card Title",
  "description": "Card description text",
  "subtasks": [
    {
      "id": "123",
      "title": "Subtask title",
      "description": "Optional description",
      "completed": false
    }
  ],
  "comments": [
    {
      "id": "456",
      "text": "Comment text",
      "author": "Author Name",
      "created_at": "2023-12-01T10:00:00Z"
    }
  ]
}

API Integration

The server uses the official Businessmap API v2 endpoints:

Endpoints:

GET  {KANBANIZE_BASE_URL}/api/v2/cards/{card_id}              # Card details
GET  {KANBANIZE_BASE_URL}/api/v2/cards/{card_id}/comments     # Comments
GET  {KANBANIZE_BASE_URL}/api/v2/cards/{card_id}/subtasks     # Subtasks
POST {KANBANIZE_BASE_URL}/api/v2/cards/{card_id}/comments     # Add comment

Authentication:

apikey: {KANBANIZE_API_KEY}

Project Structure

businessmap-mcp/
ā”œā”€ā”€ README.md                 # This documentation
ā”œā”€ā”€ LICENSE                   # Apache License 2.0
ā”œā”€ā”€ CONTRIBUTING.md           # Contribution guidelines
ā”œā”€ā”€ main.go                   # MCP server entry point
ā”œā”€ā”€ go.mod                    # Go module definition
ā”œā”€ā”€ go.sum                    # Go dependencies
ā”œā”€ā”€ .env.example             # Environment variables template
ā”œā”€ā”€ .gitignore               # Git ignore rules
ā”œā”€ā”€ internal/
ā”‚   ā”œā”€ā”€ config/
ā”‚   ā”‚   ā””ā”€ā”€ config.go        # Configuration management
ā”‚   ā””ā”€ā”€ kanbanize/
ā”‚       ā”œā”€ā”€ client.go        # Kanbanize API client
ā”‚       ā””ā”€ā”€ types.go         # API response types
ā””ā”€ā”€ tests/
    ā”œā”€ā”€ test_mcp.sh          # Shell script testing
    ā”œā”€ā”€ test_interactive.py  # Interactive Python testing
    ā””ā”€ā”€ test_messages.jsonl  # Manual JSON-RPC testing

Error Handling

The server provides robust error handling with graceful degradation:

  • šŸš« Missing Configuration: Fails fast on startup if API credentials are missing
  • āŒ Invalid Card ID: Clear error messages for empty or invalid card IDs
  • šŸŒ API Errors: Forwards Businessmap API error messages with context
  • šŸ“Š Partial Data: Returns available data with empty arrays for missing comments/subtasks
  • šŸ”— Network Issues: Detailed error reporting for connectivity problems

Security Features

  • šŸ”’ Environment-based Secrets: API keys stored in environment variables only
  • šŸš« No Secret Logging: Credentials never appear in logs or error messages
  • šŸ” HTTPS Only: All API communications use secure HTTPS connections
  • šŸ›”ļø Secure by Default: No elevated privileges required for execution

Dependencies

Contributing

Contributions are welcome! Please read for guidelines.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: 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 Apache License 2.0 - see the file for details.

Support

  • Issues: Report bugs or request features via GitHub Issues
  • Documentation: Full API documentation available in this README
  • Community: Contributions and feedback welcome!