BusinessMap MCP Server

A Model Context Protocol (MCP) server for integrating BusinessMap (formerly Kanbanize) with MCP-compatible applications.

Features

• Board Management: List workspaces and boards

• Card Operations: Search, view, create, and update cards

• User Management: List team members

• Search Capabilities: Find cards by title across boards

Related MCP server: businessmap-mcp

Architecture

The server is organized into separate modules for maintainability:

• businessmap_client.py - BusinessMap API client

• businessmap_tools.py - MCP tool implementations

• businessmap_mcp_server.py - Main server entry point

Available Tools

Information Tools

• list_workspaces() - Get all workspaces

• list_boards() - Get all boards

• list_users() - Get all users

• get_board_cards(board_id, limit=50) - Get cards from a specific board

• get_card_details(card_id) - Get detailed card information

• search_cards(query, board_id=None, limit=20) - Search cards by title

Management Tools

• create_card(template_type, title, description="") - Create new cards

• update_card(card_id, title=None, description=None) - Update existing cards

Setup

1. Install Dependencies

This project uses uv for dependency management.

cd businessmap-mcp-server
uv sync

Alternatively, run the setup script:

./setup.sh

2. Set Environment Variables

You need to configure your BusinessMap credentials:

export BUSINESSMAP_SUBDOMAIN="YOUR_SUBDOMAIN_HERE"
export BUSINESSMAP_API_KEY="your-api-key-here"

Or create a .env file:

BUSINESSMAP_SUBDOMAIN=YOUR_SUBDOMAIN_HERE
BUSINESSMAP_API_KEY=your-api-key-here

3. Test the Server

uv run python businessmap_mcp_server.py

Claude Code Integration

To use with Claude Code, add this server to your MCP settings:

Option 1: Using stdio transport

Add to your Claude Code settings (~/.config/claude-code/settings/default.json):

{
  "mcpServers": {
    "businessmap": {
      "command": "python",
      "args": ["/path/to/businessmap-mcp-server/businessmap_mcp_server.py"],
      "env": {
        "BUSINESSMAP_SUBDOMAIN": "YOUR_SUBDOMAIN_HERE", 
        "BUSINESSMAP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Using uv (recommended)

{
  "mcpServers": {
    "businessmap": {
      "command": "uv",
      "args": ["--directory", "/path/to/businessmap-mcp-server", "run", "python", "businessmap_mcp_server.py"],
      "env": {
        "BUSINESSMAP_SUBDOMAIN": "YOUR_SUBDOMAIN_HERE",
        "BUSINESSMAP_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage Examples

Once configured, you can use these commands in Claude Code:

• "List all my BusinessMap boards"

• "Show me cards in the Development board"

• "Search for cards about 'authentication'"

• "Create a new card in board 3 with title 'Fix login bug'"

• "Get details for card 14193"

• "Update card 14193 with a new description"

API Reference

BusinessMap API Integration

This server uses BusinessMap's REST API v2. The following endpoints are supported:

• GET /workspaces - List workspaces

• GET /boards - List boards

• GET /cards - List cards (with filtering)

• GET /cards/{id} - Get card details

• GET /users - List users

• POST /cards - Create cards

• PATCH /cards/{id} - Update cards

Security Notes

• Store your API key securely

• Use environment variables rather than hardcoding credentials

• The API key has full access to your BusinessMap account

• Consider creating a dedicated API key for this integration

Troubleshooting

Common Issues

1. Authentication Error: Verify your API key and subdomain are correct

2. Connection Error: Check your internet connection and BusinessMap service status

3. Permission Error: Ensure your API key has appropriate permissions

Debug Mode

Enable debug logging:

export LOG_LEVEL=DEBUG
uv run python businessmap_mcp_server.py

Contributing

Feel free to extend this server with additional BusinessMap API endpoints or features.