BD CRM Analytics — MCP server

A read-only MCP server that exposes the Meissasoft BD Leads CRM analytics (win rate, conversion funnel, connects economics, sales velocity, forecast, and lead lookup) to MCP clients like Cursor and Claude Desktop.

It talks only to the CRM public API (/api/v1/) using a Personal Access Token (X-Api-Key). It never writes anything — every tool is a GET. What a token can see is governed entirely by the CRM: a token only returns analytics if its owning user is a workspace admin AND (the workspace owner OR has been granted analytics access).

Tools

Analytics tools accept an optional date range: date_filter (e.g. this_month, last_month, last_3_months) or an explicit start_date/end_date (YYYY-MM-DD). Omit for all-time.

Related MCP server: Uniware Vtiger MCP Server

1. Prerequisites

• Node.js 18+ (uses the built-in fetch).

2. Install & build

cd bd-crm-mcp
npm install
npm run build      # compiles to dist/

3. Mint a CRM Personal Access Token

1. Sign in to the CRM (e.g. https://bd-crm.meissasoft.com) as a user who can see BD Insights — i.e. a workspace admin who is the workspace owner or has been granted analytics access. (If your token's user isn't allowed, every tool returns a clear 403 — that's expected.)

2. Go to Profile → Settings → Personal access tokens (API tokens) and create a token.

3. Copy it — it looks like plane_api_xxxxxxxx…. Store it as CRM_API_TOKEN.

Find the other values:

• WORKSPACE_SLUG — the workspace segment in the CRM URL, e.g. bd-leads in …/bd-leads/projects/….

• PROJECT_ID — open the BD Leads project; it's the UUID in the URL: …/projects/<PROJECT_ID>/….

4. Environment variables

For local testing you can copy .env.example to .env; when wired into a client, set them in the client config (below) instead.

5. Configure your MCP client

Use the absolute path to the built dist/index.js.

Cursor

Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:

{
  "mcpServers": {
    "bd-crm-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/bd-crm-mcp/dist/index.js"],
      "env": {
        "CRM_BASE_URL": "https://bd-crm.meissasoft.com",
        "CRM_API_TOKEN": "plane_api_xxxxxxxxxxxxxxxxxxxx",
        "WORKSPACE_SLUG": "bd-leads",
        "PROJECT_ID": "99361d89-81b6-4eee-83a6-24e622182383"
      }
    }
  }
}

Reload Cursor; the bd-crm-analytics tools appear in the MCP tool list.

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "bd-crm-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/bd-crm-mcp/dist/index.js"],
      "env": {
        "CRM_BASE_URL": "https://bd-crm.meissasoft.com",
        "CRM_API_TOKEN": "plane_api_xxxxxxxxxxxxxxxxxxxx",
        "WORKSPACE_SLUG": "bd-leads",
        "PROJECT_ID": "99361d89-81b6-4eee-83a6-24e622182383"
      }
    }
  }
}

Fully quit and reopen Claude Desktop. Ask e.g. "What's our win rate by profile this quarter?" or "Show the conversion funnel and biggest leak."

Windows note: if node isn't on Claude Desktop's PATH, use its full path (e.g. "command": "C:\\Program Files\\nodejs\\node.exe") and a double-backslashed args path.

Hosted service — web chat + remote MCP (server/)

Everything above is the local stdio server, unchanged. The same repo also ships a hosted service (server/) that reuses the same CrmClient and the same 7 tools, and adds three network surfaces behind one URL (https://bd-crm.meissasoft.com/mcp):

Auth model. Login is separate from data fetching. To sign in, a person presents their own CRM personal token; the service verifies it passes the analytics gate (workspace admin and owner-or-analytics-flag), captures their identity, then discards the token. All data is fetched with a single server-side CRM_ADMIN_TOKEN — the browser never sees it, and the ANTHROPIC_API_KEY is server-side only. The remote MCP endpoint uses the same check on the token sent in its header.

Environment (hosted only)

The chat backend calls an OpenAI-compatible chat/completions API (OpenRouter by default), so the provider is just LLM_BASE_URL + LLM_API_KEY. The model is pinned in one place — DEFAULT_LLM_MODEL in server/config.ts (currently anthropic/claude-sonnet-5) — and any deploy can override it with LLM_MODEL. Only the LLM-call layer is provider-specific; the 7 tools and the CrmClient (env admin token) wiring are unchanged.

Mint CRM_ADMIN_TOKEN: sign in to the CRM as the workspace owner (or an admin with analytics access), go to Profile → Settings → Personal access tokens, create one, and set it as CRM_ADMIN_TOKEN. This is the only token stored, and it lives only in the server env.

Run locally

npm install
npm run build:server
CRM_BASE_URL=http://localhost:8001 \
CRM_ADMIN_TOKEN=plane_api_… \
WORKSPACE_SLUG=bd-leads \
PROJECT_ID=99361d89-… \
SESSION_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))") \
LLM_API_KEY=sk-or-v1-…  \
PORT=8790 npm run start:server
# open http://localhost:8790/mcp   (dev live-reload: npm run dev:server)

Connect Claude Desktop to the remote MCP endpoint

Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/…, Windows: %APPDATA%\Claude\…). It uses mcp-remote to bridge stdio ↔ the remote HTTP endpoint, sending your own CRM token as a header:

{
  "mcpServers": {
    "bd-crm-analytics": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://bd-crm.meissasoft.com/mcp/rpc",
        "--header", "X-Api-Key:plane_api_xxxxxxxxxxxxxxxxxxxx"
      ]
    }
  }
}

X-Api-Key:<token> (no space) sidesteps a known mcp-remote header-parsing quirk. If you prefer a bearer token, use "--header", "Authorization:Bearer plane_api_…" — but keep it one token with no space after the header name, or pass it via an env-substituted value. Fully quit and reopen Claude Desktop; the tools appear. Your token must pass the analytics gate or every call returns a readable 401/403.

Deploy (reference — not auto-applied)

Nothing environment-specific is hardcoded — the service reads everything from env, so dev and prod differ only by their .env file:

• .env.local.example — dev values (CRM_BASE_URL=http://localhost:8001, dev PROJECT_ID).

• .env.prod.example — prod values (CRM_BASE_URL=https://bd-crm.meissasoft.com, prod PROJECT_ID).

Both carry placeholders only for CRM_ADMIN_TOKEN, LLM_API_KEY, SESSION_SECRET.

Build & push the image to GHCR (same flow as the CRM image), then deploy from it:

export MCP_IMAGE_TAG=$(git rev-parse --short HEAD)      # or a semver, e.g. v1.0.0
echo "$GHCR_PAT" | docker login ghcr.io -u <github-username> --password-stdin
docker build -t ghcr.io/meissasoft/bd-crm-mcp:$MCP_IMAGE_TAG \
             -t ghcr.io/meissasoft/bd-crm-mcp:latest .
docker push ghcr.io/meissasoft/bd-crm-mcp:$MCP_IMAGE_TAG
docker push ghcr.io/meissasoft/bd-crm-mcp:latest

On the host:

cp .env.prod.example .env      # then fill the 3 secrets
docker compose up -d bd-crm-mcp

• Dockerfile — builds server/ and runs server/dist/server/main.js on PORT.

• deploy/docker-compose.snippet.yml — isolated service block; image: from GHCR, every value via ${VAR} (no baked IDs/URLs). Caddy network is a TODO to fill after inspecting the stack.

• deploy/Caddyfile.snippet — routes /mcp/* to the container (flush_interval -1 for SSE).

Deploy is a separate, deliberate step: push the image, set the .env, add the container + Caddy route, and confirm the CRM app is untouched.

Behavior & troubleshooting

• Read-only. No tool creates, edits, or deletes anything.

• 401 → token missing/invalid/expired: check CRM_API_TOKEN.

• 403 → the token's user lacks analytics access (needs workspace admin + owner-or-flag).

• 404 → check CRM_BASE_URL and WORKSPACE_SLUG.

• Errors are returned as readable tool results; the server does not crash.

• Estimated figures (deal value, revenue-per-connect, velocity, forecast) come straight from the CRM's deal-value proxy and are labelled as estimates there.

Development

npm run dev     # run from source with tsx (no build step)