Businessmap MCP

🚀 BusinessMap MCP Server

A Model Context Protocol server for integrating with BusinessMap (Kanbanize), offering full access to various project - management features in BusinessMap.

🚀 Quick Start

The BusinessMap MCP server is a powerful tool that allows comprehensive access to BusinessMap's project - management features. You can get started by installing it and configuring the necessary environment variables.

✨ Features

Advanced Card Management

• Complete CRUD operations: Offers full - fledged Create, Read, Update, and Delete operations for cards, subtasks, and relationships.
• Parent - child card hierarchies: Enables full graph traversal of parent - child card relationships.
• Outcome tracking and history: Facilitates detailed progress monitoring through outcome tracking and history.
• Linked cards management: Manages cross - project dependencies with linked cards.
• Custom fields and types: Supports custom fields and types for flexible workflows.

Comprehensive Board Operations

• Multi - workspace board management: Allows managing boards across multiple workspaces with search capabilities.
• Column and lane (swimlane) operations: Customizes workflows with column and lane operations.
• Board structure analysis: Provides detailed metadata for board structure analysis.

Workflow Intelligence

• Cycle time analysis: Conducts cycle time analysis with configurable column sets.
• Effective cycle time tracking: Tracks effective cycle time for performance optimization.
• Custom field integration: Integrates custom fields for enhanced reporting.

Enterprise Features

• Read - only mode: Ensures safe data exploration.
• Robust error handling: Displays detailed error messages.
• Automatic connection verification: Verifies connections automatically with retry logic.
• Docker support: Supports containerized deployments.

📦 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

💻 Usage Examples

Basic Usage

The BusinessMap MCP server provides a variety of tools for different aspects of BusinessMap management. For example, to list all workspaces:

# Assuming the server is running and configured correctly
# Use the appropriate MCP client command to call the list_workspaces tool

Advanced Usage

If you want to create a new card with specific properties, you can use the create_card tool. The exact command depends on your MCP client configuration.

📚 Documentation

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)

Claude Desktop

Add the following configuration to your claude_desktop_config.json file: Using NPX:

{
  "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
      }
    }
  }
}

Using Global Installation:

{
  "mcpServers": {
    "Businessmap": {
      "command": "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
      }
    }
  }
}

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

Manual Setup

1. Clone this repository:

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

2. Install dependencies:

npm install

3. 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

⚠️ Important 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.

4. Build the project:

npm run build

5. 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

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:

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:

1. Check your environment variables:

echo $BUSINESSMAP_API_URL
echo $BUSINESSMAP_API_TOKEN

2. Test the connection manually:

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

3. 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:

1. Configuration validation - Checks all required environment variables
2. API connection verification - Tests connectivity with up to 3 retry attempts
3. Authentication check - Verifies API token permissions
4. 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)
npm run publish

The release process automatically:

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

Contributing

1. Follow conventional commit format for better release notes:

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

2. Ensure all tests pass before submitting PR:

npm test
npm run test:npx

🔧 Technical Details

The BusinessMap MCP server is built with TypeScript and Node.js. It interacts with the BusinessMap API to provide various project - management tools. The server uses environment variables for configuration and supports Docker for containerized deployments.

📄 License

This project is licensed under the MIT License.

💡 Usage Tip

For issues and questions:

1. Check the Issues page
2. Review BusinessMap API documentation
3. Verify your environment configuration
4. Submit a new issue with detailed information

Related Projects

• Model Context Protocol - Official MCP documentation
• BusinessMap API Documentation - Official API reference
• MCP TypeScript SDK - Official MCP SDK