BusinessMap MCP Server

Model Context Protocol server for BusinessMap (Kanbanize) integration. Provides comprehensive access to BusinessMap's project management features through 56 tools, 5 resources, and 4 guided prompts — covering workspaces, boards, cards, subtasks, parent-child relationships, outcomes, comments, tags, stickers, predecessors, 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 mode (optional, defaults to 3000)
• TRANSPORT: Set to stdio (default) or http
• ALLOWED_ORIGINS: Comma-separated CORS origin allowlist for HTTP mode (optional, defaults to http://localhost)
• ALLOWED_HOSTS: Comma-separated Host header allowlist for HTTP mode DNS rebinding protection (optional)

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

Config file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Open it via Settings → Developer → Edit Config, then add:

{
  "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",
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
      }
    }
  }
}

Note: Fully quit and restart Claude Desktop after editing (on macOS, quit from the Dock; on Windows, exit from the system tray). JSON does not support comments — remove any before saving.

Claude Code

Run the following command to add the server globally or per-project:

# Add globally (available across all projects)
claude mcp add --transport stdio --scope user businessmap -- npx -y @edicarlos.lds/businessmap-mcp

# Add to current project only (stored in ~/.claude.json)
claude mcp add --transport stdio businessmap -- npx -y @edicarlos.lds/businessmap-mcp

To pass environment variables:

claude mcp add --transport stdio \
  --env BUSINESSMAP_API_TOKEN=your_token_here \
  --env BUSINESSMAP_API_URL=https://your-account.kanbanize.com/api/v2 \
  businessmap -- npx -y @edicarlos.lds/businessmap-mcp

Alternatively, commit a .mcp.json file to your project root to share it with your team:

{
  "mcpServers": {
    "businessmap": {
      "command": "npx",
      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "${BUSINESSMAP_API_TOKEN}",
        "BUSINESSMAP_API_URL": "${BUSINESSMAP_API_URL}"
      }
    }
  }
}

Tip: Use environment variable expansion (${VAR}) in .mcp.json to avoid hardcoding secrets in source control.

Cursor

Create or edit ~/.cursor/mcp.json (global) or .cursor/mcp.json at the project root (project-specific):

{
  "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",
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
      }
    }
  }
}

You can also manage servers via Settings → Features → MCP in the Cursor UI.

VS Code

VS Code uses "servers" as the top-level key (not "mcpServers"). Create or edit .vscode/mcp.json in your project root (workspace-scoped, safe to commit), or the user-level config at:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "businessmap-token",
      "description": "BusinessMap API Token",
      "password": true
    }
  ],
  "servers": {
    "businessmap": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "${input:businessmap-token}",
        "BUSINESSMAP_API_URL": "https://your-account.kanbanize.com/api/v2",
        "BUSINESSMAP_READ_ONLY_MODE": "false",
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
      }
    }
  }
}

Note: The inputs block lets VS Code prompt you for secrets at runtime instead of hardcoding them. Requires the GitHub Copilot Chat extension. Add via Command Palette: MCP: Add Server.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (open from the Cascade panel's MCPs icon → Configure):

{
  "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",
        "BUSINESSMAP_DEFAULT_WORKSPACE_ID": "1"
      }
    }
  }
}

Tip: Windsurf supports ${env:VARIABLE_NAME} syntax inside env values to reference host environment variables.

Zed

MCP servers are configured inside Zed's main settings file (~/.config/zed/settings.json) under the context_servers key. Open it via Zed → Settings or Cmd+,:

{
  "context_servers": {
    "businessmap": {
      "source": "custom",
      "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"
      }
    }
  }
}

You can also add servers via the Agent Panel's Settings view (Add Custom Server). A green indicator dot in the Agent Panel confirms the server is running.

Other MCP Clients

For any other MCP-compatible client, configure a stdio server with:

• Command: npx -y @edicarlos.lds/businessmap-mcp
• Required env vars: BUSINESSMAP_API_TOKEN, BUSINESSMAP_API_URL
• Optional env vars: BUSINESSMAP_READ_ONLY_MODE, BUSINESSMAP_DEFAULT_WORKSPACE_ID, LOG_LEVEL

Remote Usage (Streamable HTTP)

You can run the server as a remote MCP endpoint over Streamable HTTP. This is useful for deploying to cloud providers or using clients that support remote MCP connections.

1. Start the server in HTTP mode:

   export TRANSPORT=http
   export PORT=3000
   export ALLOWED_ORIGINS=https://your-client.example.com
   export ALLOWED_HOSTS=your-server.example.com
   npm start
   

2. Connect your client:

   Configure your MCP client to connect to the Streamable HTTP endpoint:

   • URL: http://your-server:3000/mcp

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
   

   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 tools, resources, and prompts for comprehensive project management integration.

Tools

Workspace Management

• list_workspaces - Get all workspaces
• get_workspace - Get workspace details
• `create

---