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:

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