Businessmap MCP Support – Overview & Setup Guide – Businessmap Knowledge Base

Introduction

Businessmap now provides native MCP (Model Context Protocol) support, enabling seamless integrations with AI tools such as Cursor, Claude Desktop, Claude Code CLI and others.

This new capability gives teams a unified and structured way to interact with Businessmap through AI agents, automations, and external systems that rely on MCP.

Customers have been increasingly requesting AI interoperability, and the new MCP server lays the groundwork for deeper native integrations—both customer-driven and internally built.

What Is the Businessmap MCP Server?

The Businessmap MCP Server exposes a standardized interface for external AI tools, enabling them to read, search, create, and update work items (cards) in a safe and structured way.

It allows AI systems to:

Retrieve card information
Manage cards (create, update, move)
Work with subtasks
Manage comments
Interpret complex prompts that combine multiple steps (e.g., “Create a card, add a comment, then move it to In Progress.”)

Supported Functional Areas

The MCP server organizes functionality into four major categories:

1. Card Information

Method	Description
get_card_details	Returns full details for a specific card (title, description, custom fields, etc.).
get_card_comments	Retrieves all comments associated with a card.
get_card_flow_history	Shows the card’s movement across boards/workflows/columns with timing details.
get_card_blocked_times	Shows full blocking history, including when and where blocks occurred.
get_card_change_history	Chronological history of all edits made to the card.
get_card_logged_time	Time logged on the card and its subtasks.
get_card_children_hierarchy	Retrieves the hierarchical structure of the card’s children.
get_card_links	Lists all card links: parents, children, relatives, predecessors, successors.

2. Card Management

Method	Description
search_cards	Search for cards based on multiple criteria (see full list below).
create_card	Creates a new card with specified details.
update_card_details	Updates fields of an existing card.
move_card	Moves a card to a different column, workflow, or board.

3. Subtasks

Method	Description
get_card_subtasks	Retrieves all subtasks for a card.
add_card_subtask	Adds a new subtask.
update_subtask	Updates an existing subtask.
delete_card_subtask	Removes a subtask from a card.

4. Comments

Method	Description
add_card_comment	Adds a comment to a card.
update_card_comment	Edits an existing comment.
delete_card_comment	Deletes a comment.

Card Search Criteria

The search_cards method supports advanced filtering across multiple categories:

Location & Structure

board_names
workflow_names
column_names
lane_names

Text Search

title
description
custom_id

People

owner_usernames

Time Filters

created_at_from / to
deadline_from / to

Card Characteristics

priority_names (Critical, High, Average, Low)
size_min / size_max
is_blocked
type_names

Metadata

tag_names
sticker_names

Examples:

“Show all critical cards in Board X.”
“Find cards with deadlines this month.”
“Show all blocked cards assigned to John.”
“Search for cards tagged Urgent in In Progress.”
“Find all cards sized 5–10 in the Development workflow.”

Installing and Configuring the Businessmap MCP Server

1. MCP Setup in Cursor

Important: Running MCP in Cursor requires Node.js with npm installed on your machine.

Cursor automatically loads MCP configurations from:

.cursor/mcp.json

To configure Businessmap MCP in Cursor:

Open the file above.
Include the MCP configuration, which should look like this:

{
  "mcpServers": {
    "businessmap-cards": {
      "command": "npx",
      "args": [
        "@bmapio/mcp-client-cards"
      ],
      "env": {
        "COMPANY_NAME": "XXX",
        "API_KEY": "XXX"
      }
    }
  }
}

Cursor will automatically install or refresh the MCP server when this file changes. If the configuration is successful, you should see Cursor connected to the MCP:

2. MCP Setup in Claude Desktop

Important: Running MCP in Claude Desktop requires Node.js with npm installed on your machine.

Open Settings → Developer.
Add a new MCP server by editing the Config file (click Edit Config to locate the file on your file system)
Include the MCP configuration, which should look like this:

{
  "mcpServers": {
    "businessmap-cards": {
      "command": "npx",
      "args": [
        "@bmapio/mcp-client-cards"
      ],
      "env": {
        "COMPANY_NAME": "XXX",
        "API_KEY": "XXX"
      }
    }
  }
}

After steps 1, 2 and 3 above, restart Claude Desktop (quit/kill the process and start it again). If the installation is successful, you should see the server listed and connected.

3. MCP Setup via Claude Code CLI

Important: Running MCP in Claude Code CLI requires Node.js with npm installed on your machine. MCP is not currently supported in the VisualStudio mode of Claude Code.

Setup steps:

Navigate to the project folder where you want the MCP server available.
Run the following command, replacing the subdomain/apikey placeholders:

claude mcp add --transport stdio businessmap-cards \
  --env COMPANY_NAME=YOUR_SUBDOMAIN \
  --env API_KEY=YOUR_API_KEY \
  -- npx @bmapio/mcp-client-cards

This registers the Businessmap MCP server for use inside Claude Code. To verify the installation, run claude and start the commend /mcp. If the installation is correct, you will see the server connected as shown below:

Good to Know

Each AI tool (Cursor, Claude Desktop, Claude Code) can introspect the MCP server itself, meaning the full list of tools and their parameters can be discovered directly from within the AI assistant—no need to manually browse an API reference.
MCP enables complex AI workflows, such as multi-step card operations, performed in a single prompt.
The configuration is lightweight: only a subdomain and API key are required.
To use the MCP server, you need to have the Security control "Enable AI" on:

Articles in this section