BusinessMap MCP Server

Model Context Protocol (MCP) server for BusinessMap/Kanbanize. It gives AI clients access to BusinessMap workspaces, boards, cards, users, custom fields, workflow cycle-time data, resources, and guided prompts.

What You Get

• 27 agent-oriented MCP tools by default, with a 93-tool full profile for advanced operations
• 6 MCP resources for direct workspace, board, and paginated card reads
• 4 guided prompts for board analysis, reporting, card creation, and workspace summaries
• Optional read-only mode for safer exploration
• stdio transport for local MCP clients and HTTP transport for remote usage
• Docker, structured logging, and programmatic middleware support

See the full catalog in docs/TOOLS.md.

Quick Start

Run directly with npx:

npx -y @edicarlos.lds/businessmap-mcp

Or install globally:

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

The server requires Node.js 22 or newer.

Required Configuration

Set these environment variables in your MCP client, shell, deployment platform, or local .env file:

BUSINESSMAP_API_TOKEN=your_token_here
BUSINESSMAP_API_URL=https://your-account.kanbanize.com/api/v2

Optional settings:

Variable	Default	Description
BUSINESSMAP_READ_ONLY_MODE	false	Use true to register only read-only tools.
BUSINESSMAP_DEFAULT_WORKSPACE_ID	unset	Default workspace ID for tools that can use one.
BUSINESSMAP_TOOL_PROFILE	essential	Agent-oriented catalog with progressive disclosure. Use full for all advanced operations.
LOG_LEVEL	1	0 debug, 1 info, 2 warn, 3 error, 4 none.
LOG_FORMAT	text	Use json for structured logs.
TRANSPORT	stdio	Use stdio or http.
PORT	3000	HTTP server port.
ALLOWED_ORIGINS	http://localhost	CORS allowlist for HTTP mode.
ALLOWED_HOSTS	unset	Host header allowlist for HTTP mode.
HTTP_BODY_LIMIT	1mb	Maximum JSON request body size (b, kb, or mb).
HTTP_MAX_SESSIONS	100	Maximum concurrent initialized HTTP sessions.
HTTP_SESSION_TIMEOUT_MS	1800000	Idle session timeout in milliseconds.

MCP Client Setup

Most MCP clients need the same command and environment variables:

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

Client-specific examples for Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, and other MCP clients are in docs/MCP_CLIENTS.md.

HTTP Mode

Use HTTP mode when deploying the server remotely or when your client supports Streamable HTTP:

Security: The HTTP transport does not enable authentication by default. Do not expose it publicly without TLS, authentication, authorization, and rate limiting. See Programmatic middleware and Security Policy.

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

Configure your MCP client with:

http://your-server:3000/mcp

Use /health for liveness and /ready for readiness. The server stops accepting new sessions when capacity is exhausted and closes active sessions gracefully on SIGINT or SIGTERM.

For custom authentication, authorization, logging, or rate limiting, see docs/MIDDLEWARE.md.

Local Development

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

Create a local .env file:

This is the beginning of the README. Read the rest at the original. Read the full README ↗