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

Up to 92 MCP tools for workspaces, boards, cards, docs, users, custom fields, workflow management, batch board setup, and health checks
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`	`full`	Use `essential` for a smaller, general-purpose tool catalog.
`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:

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

Useful commands:

npm run dev          # Run from TypeScript source
npm run watch        # Run and reload on changes
npm run build        # Build dist/
npm test             # Run tests
npm run lint         # Run ESLint
npm run test:npx     # Test package execution through npx

Docker

npm run docker:build
npm run docker:up
npm run docker:logs
npm run docker:down

Troubleshooting

If startup fails, check the two required environment variables first:

echo $BUSINESSMAP_API_URL
echo $BUSINESSMAP_API_TOKEN

Then test the BusinessMap connection:

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

Common causes:

BUSINESSMAP_API_URL is not in the expected format: https://your-account.kanbanize.com/api/v2
BUSINESSMAP_API_TOKEN is missing, expired, or lacks the needed permissions
The selected MCP client has not been fully restarted after editing its config

Logging details are documented in docs/LOGGING.md.

Project Docs

Contributing

See CONTRIBUTING.md for local setup, project structure, and pull request guidance.

Use conventional commits when possible:

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

Before opening a pull request:

npm run lint
npm test -- --runInBand
npm run build
npm run knip

npm run test:npx is an optional API-backed smoke test and requires BusinessMap credentials.

Support

For issues and questions:

Check existing GitHub issues
Review the BusinessMap API documentation
Verify your environment configuration
Open a new issue with the error message, runtime command, and relevant MCP client configuration

Related Projects

License

MIT

Businessmap MCP

README