BusinessMap

npm version GitHub release npm downloads License: MIT Node.js Version TypeScript MCP GitHub Sponsors

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

• Tools, resources, and prompts
• MCP client configuration
• Logging
• Programmatic middleware
• Release process
• Scripts

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:

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

Related Projects

• Model Context Protocol
• BusinessMap API Documentation
• BusinessMap Demo API
• MCP TypeScript SDK

Sponsors

If this project helps you, consider supporting it through GitHub Sponsors.

License

MIT