mcp-crm

A learning project: a Model Context Protocol server that exposes a CRM to an MCP client over stdio.

Sign-in goes through Microsoft Entra using the device-code flow. The resulting identity token is exchanged for a CRM access token, so CRM queries run as the signed-in user and return only what that user is allowed to see.

Requirements

• Node.js 20+

• An Entra app registration with the device-code (public client) flow enabled

• A CRM API implementing the contract below

Related MCP server: ff-crm-mcp

Setup

npm install

Copy .env.example to .env and fill it in:

cp .env.example .env

ENTRA_CLIENT_ID, ENTRA_TENANT_ID, and CRM_API_BASE_URL are required — the server throws on startup if any is missing. .env is gitignored; never commit it.

CRM contract

The server targets any CRM exposing these three routes. Paths are relative to CRM_API_BASE_URL and can be remapped with the optional CRM_AUTH_PATH and CRM_ACCOUNTS_PATH variables, so a CRM that mounts them elsewhere needs no code change.

All CRM requests send Authorization: Bearer <access_token>, so results reflect the signed-in user's own permissions.

Running

npx tsx src/index.ts     # run directly
npx tsc                  # type-check and build to dist/

The server speaks MCP over stdio, so it is normally launched by a client rather than by hand. To register it with Claude Code:

{
  "mcpServers": {
    "crm": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-crm/src/index.ts"]
    }
  }
}

Log output goes to stderr, since stdout carries the MCP protocol.

Tools

Sign-in flow

start_crm_login cannot block until Entra finishes, so it is split in two:

1. Call start_crm_login. It returns the device code and the URL to open.

2. Complete sign-in in the browser.

3. Call crm_login_status to confirm. Once it reports a signed-in user, search_crm_accounts and get_crm_account will work.

The token is held in memory only — restarting the server means signing in again.

License

ISC — see LICENSE.