BusinessMap MCP Server

Model Context Protocol server for BusinessMap (Kanbanize) integration. Provides comprehensive access to BusinessMap's project management features including workspaces, boards, cards, subtasks, parent-child relationships, outcomes, custom fields, and more.

Installation

Via NPX (Recommended)

You can run the BusinessMap MCP server directly using npx without installing it globally:

npx @edicarlos.lds/businessmap-mcp

Global Installation

npm install -g @edicarlos.lds/businessmap-mcp

Configuration

Environment Variables

The server requires the following environment variables:

BUSINESSMAP_API_TOKEN: Your BusinessMap API token
BUSINESSMAP_API_URL: Your BusinessMap API URL (e.g., https://your-account.kanbanize.com/api/v2)
BUSINESSMAP_READ_ONLY_MODE: Set to "true" for read-only mode, "false" to allow modifications (optional, defaults to "false")
BUSINESSMAP_DEFAULT_WORKSPACE_ID: Set the BusinessMap workspace ID (optional)
LOG_LEVEL: Set logging verbosity - 0 (DEBUG), 1 (INFO), 2 (WARN), 3 (ERROR), 4 (NONE) (optional, defaults to 1)
PORT: Server port for HTTP/SSE mode (optional, defaults to 3000)
TRANSPORT: Set to stdio (default), sse, or http to switch transport modes

Local Usage with .env

When running locally (e.g., via npx or npm start), the server will automatically look for a .env file in your current working directory.

# Create a .env file
echo "BUSINESSMAP_API_TOKEN=your_token" > .env
echo "BUSINESSMAP_API_URL=https://..." >> .env

# Run the server
npx @edicarlos.lds/businessmap-mcp

Claude Desktop

Add the following configuration to your claude_desktop_config.json file:

{
  "mcpServers": {
    "Businessmap": {
      "command": "npx",
      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token_here",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "BUSINESSMAP_READ_ONLY_MODE": "false", // optional
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1" // optional
      }
    }
  }
}

Cursor

To use the BusinessMap MCP server with Cursor, add the following configuration to your Cursor settings:

Open Cursor Settings (Cmd/Ctrl + ,)
Click on "MCP & Integrations" and then "Add Custom MCP"
Add a new MCP server with the following configuration:

{
  "name": "BusinessMap",
  "command": "npx",
  "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
  "env": {
    "BUSINESSMAP_API_TOKEN": "your_token_here",
    "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
    "BUSINESSMAP_READ_ONLY_MODE": "false",
    "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
  }
}

VSCode

To use the BusinessMap MCP server with VSCode, add the following configuration:

Edit or create .vscode/mcp.json and add the MCP extension settings:

{
  "servers": {
    "businessmap": {
      "command": "npx",
      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token_here",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "BUSINESSMAP_READ_ONLY_MODE": "false",
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
      }
    }
  }
}

Other MCP Clients

For other MCP clients, use the appropriate configuration format for your client, ensuring you specify:

Command: npx @edicarlos.lds/businessmap-mcp (or businessmap-mcp if globally installed)
Environment variables: BUSINESSMAP_API_TOKEN, BUSINESSMAP_API_URL, and optionally BUSINESSMAP_READ_ONLY_MODE, BUSINESSMAP_DEFAULT_WORKSPACE_ID

Remote Usage (HTTP/SSE)

You can run the server as a remote HTTP endpoint using Server-Sent Events (SSE). This is useful for deploying to cloud providers or using with clients that support remote MCP servers.

Start the server in HTTP mode:

export TRANSPORT=sse
export PORT=3000
npm start

Connect your client:

Configure your MCP client to connect to the SSE endpoint:
- URL: http://your-server:3000/sse

Manual Setup

Clone this repository:

git clone https://github.com/edicarloslds/businessmap-mcp.git
cd businessmap-mcp

Install dependencies:
```
npm install
```
Create a .env file with your BusinessMap credentials (for development/testing):
```
BUSINESSMAP_API_TOKEN=your_token_here
BUSINESSMAP_API_URL=https://your-account.kanbanize.com/api/v2
BUSINESSMAP_READ_ONLY_MODE=false
BUSINESSMAP_DEFAULT_WORKSPACE_ID=1
```
Note: When using as an MCP server with Claude Desktop, you don't need a .env file. Configure the environment variables directly in your MCP client configuration instead.
Build the project:
```
npm run build
```
Start the server:
```
npm start
```

Usage

The BusinessMap MCP server provides the following tools:

Workspace Management

list_workspaces - Get all workspaces
get_workspace - Get workspace details
create_workspace - Create new workspace

Board Management

list_boards - List boards in workspace(s)
search_board - Search for boards by ID or name
get_current_board_structure - Get the complete current structure of a board including workflows, columns, lanes, and configurations
create_board - Create new board (if not in read-only mode)
get_columns - Get all columns for a board
get_lanes - Get all lanes for a board
get_lane - Get details of a specific lane/swimlane
create_lane - Create new lane/swimlane (if not in read-only mode)

Card Management

Basic Card Operations

list_cards - Get cards from a board with optional filters
get_card - Get detailed card information
get_card_size - Get the size/points of a specific card
create_card - Create new card
move_card - Move card to different column/swimlane
update_card - Update card properties
set_card_size - Set the size/points of a specific card

Card Comments

get_card_comments - Get all comments for a specific card
get_card_comment - Get details of a specific comment from a card

Card Custom Fields & Types

get_card_custom_fields - Get all custom fields for a specific card
get_card_types - Get all available card types

Card Outcomes & History

get_card_outcomes - Get all outcomes for a specific card
get_card_history - Get the history of a specific card outcome

Card Relationships

get_card_linked_cards - Get all linked cards for a specific card

Card Subtasks

get_card_subtasks - Get all subtasks for a specific card
get_card_subtask - Get details of a specific subtask from a card
create_card_subtask - Create a new subtask for a card

Card Parent Relationships

get_card_parents - Get a list of parent cards for a specific card
get_card_parent - Check if a card is a parent of a given card
add_card_parent - Make a card a parent of a given card
remove_card_parent - Remove the link between a child card and a parent card
get_card_parent_graph - Get a list of parent cards including their parent cards too
get_card_children - Get a list of child cards of a specified parent card

Custom Field Management

get_custom_field - Get details of a specific custom field by ID

Workflow & Cycle Time Analysis

get_workflow_cycle_time_columns - Get workflow's cycle time columns
get_workflow_effective_cycle_time_columns - Get workflow's effective cycle time columns

User Management

list_users - Get all users
get_user - Get user details
get_current_user - Get current logged user details

System

health_check - Check API connection
get_api_info - Get API information

Tool Summary

The BusinessMap MCP server provides 42 tools across 7 categories:

Workspace Management: 3 tools
Board Management: 8 tools
Card Management: 23 tools (organized in 6 subcategories)
Custom Field Management: 1 tool
Workflow & Cycle Time Analysis: 2 tools
User Management: 3 tools
System: 2 tools

Key Features

Advanced Card Management

Complete CRUD operations for cards, subtasks, and relationships
Parent-child card hierarchies with full graph traversal
Outcome tracking and history for detailed progress monitoring
Linked cards management for cross-project dependencies
Custom fields and types support for flexible workflows

Comprehensive Board Operations

Multi-workspace board management with search capabilities
Column and lane (swimlane) operations for workflow customization
Board structure analysis with detailed metadata

Workflow Intelligence

Cycle time analysis with configurable column sets
Effective cycle time tracking for performance optimization
Custom field integration for enhanced reporting

Enterprise Features

Read-only mode for safe data exploration
Robust error handling with detailed error messages
Automatic connection verification with retry logic
Docker support for containerized deployments
Structured logging with multiple log levels (DEBUG, INFO, WARN, ERROR)

Logging

The server uses a structured logging system that outputs to STDERR (required for MCP protocol compatibility). You can control the verbosity using the LOG_LEVEL environment variable:

0 (DEBUG): All messages including detailed debugging information
1 (INFO): Informational messages, warnings, and errors (default)
2 (WARN): Only warnings and errors
3 (ERROR): Only error messages
4 (NONE): Disable all logging

Example configuration with custom log level:

{
  "mcpServers": {
    "Businessmap": {
      "command": "npx",
      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token_here",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "LOG_LEVEL": "0"
      }
    }
  }
}

Note: All logging uses STDERR to maintain compatibility with the MCP JSON-RPC protocol, which requires STDOUT to be reserved exclusively for protocol communication.

Development

Setup Development Environment

# Install dependencies
npm install

# Run in development mode
npm run dev

# Watch for changes
npm run watch

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

Docker Support

# Build Docker image
npm run docker:build

# Run with Docker Compose
npm run docker:up

# View logs
npm run docker:logs

# Stop containers
npm run docker:down

Troubleshooting

Connection Issues

The server now includes automatic connection verification during startup. If you encounter connection issues:

Check your environment variables:

echo $BUSINESSMAP_API_URL
echo $BUSINESSMAP_API_TOKEN

Test the connection manually:

chmod +x scripts/test-connection.sh
./scripts/test-connection.sh

Common issues:
- Invalid API URL: Ensure your URL follows the format https://your-account.kanbanize.com/api/v2
- Invalid API Token: Verify your token has the necessary permissions

Startup Process

The server now performs the following steps during initialization:

Configuration validation - Checks all required environment variables
API connection verification - Tests connectivity with up to 3 retry attempts
Authentication check - Verifies API token permissions
Server startup - Starts the MCP server only after successful connection

If the connection fails, the server will display detailed error messages and retry automatically.

Release Process

This project uses an automated release process. See RELEASE_PROCESS.md for detailed documentation.

Quick Start:

# Preview release notes
npm run preview:release

# Publish new version (interactive)
# Publish to NPM and create GitHub release (interactive flows)
npm run publish:npm && npm run publish:github

The release process automatically:

Bumps version (patch/minor/major)
Generates release notes from commits
Creates GitHub tags and releases
Publishes to NPM

Contributing

Follow conventional commit format for better release notes:

feat: add new feature
fix: resolve bug
docs: update documentation
refactor: improve code structure

Ensure all tests pass before submitting PR:
```
npm test
npm run test:npx
```

License

MIT

Support

For issues and questions:

Check the Issues page
Review BusinessMap API documentation
Verify your environment configuration
Submit a new issue with detailed information

Related Projects

Model Context Protocol - Official MCP documentation
BusinessMap API Documentation - Official API reference
BusinessMap Demo API - Interactive API documentation and testing environment
MCP TypeScript SDK - Official MCP SDK

BusinessMap