suitecrm-mcp

⚡ Securely connect AI agents to your enterprise CRM in under 5 minutes. Production-ready.

An open-source MCP (Model Context Protocol) gateway for SuiteCRM. Lets AI assistants like Claude Desktop, Claude Code, and OpenClaw read and write your CRM data via a secure, persistent SSE connection.

Built from a real production deployment. Commercial alternatives are expensive; this one is free and open-source.

Ships with a stateless architecture powered by Redis for horizontal scaling, and a full observability stack: Prometheus metrics, Grafana dashboards (33 panels), and Loki log aggregation.

🚀 Why SuiteCRM-MCP?

🛡️ Enterprise Trust & Security

Built for production environments where data integrity and privacy are non-negotiable.

• Zero-Trust for Credentials: CRM passwords never leave the gateway server. MCP clients (like Claude) hold only an opaque, revocable API key.
• Identity First: Seamlessly integrates with Auth0, Azure AD, or any OIDC provider.
• Audit Ready: Every tool call is logged with structured JSON (Loki), allowing you to see exactly what your AI agents are doing in real-time.
• Circuit Breaker Protection: Automatically shields your CRM from cascading failures if the backend becomes unresponsive.

Table of Contents

✨ Features

• 24 tools covering full CRUD, activity logging (calls, tasks, notes), bulk operations, file attachments, dropdown introspection, and more
• SSE transport - compatible with Claude Desktop, Claude Code, OpenClaw, and any MCP client that supports HTTP+SSE
• OAuth2/OIDC authentication - users log in via Auth0, Azure AD, or any OIDC provider; the gateway issues personal, revocable API keys
• No credentials on client machines - MCP clients hold only an opaque API key; CRM passwords live on the gateway
• Group-based entity access - JWT group claims gate which CRM instances each user can reach
• Session auto-renewal - CRM sessions re-authenticate transparently on expiry
• Stateless & Scalable - auth sessions and profiles cached in Redis, enabling zero-downtime restarts and horizontal scaling behind a load balancer with sticky session routing (SSE connections are per-process; the /messages endpoint must reach the same process that owns the SSE transport)
• Unified installer - one script handles single CRM (no nginx) or N CRMs behind nginx, with interactive OAuth setup
• Entity-prefixed tools - run multiple CRM instances side-by-side without name collisions
• Admin reporting - mcp-admin report generates browsable HTML activity reports from Loki and SQLite, with per-user drill-down showing call history, dry runs, and errors with module and field detail

↑ back to top

🛠️ Tools

Replace {prefix} with your configured SUITECRM_PREFIX (default: suitecrm).

Supported modules include: Accounts, Contacts, Leads, Opportunities, Cases, Calls, Meetings, Tasks, Notes, Emails, Documents, Campaigns, AOS_Quotes, AOS_Invoices, AOS_Products, AOS_Contracts, AOR_Reports, AOW_WorkFlow, SecurityGroups - and any custom modules in your instance.

↑ back to top

🏗️ Architecture

%%{init: {"flowchart": {"curve": "linear"}}}%%
flowchart TB
    IdP["🔐 Auth0 / Azure AD\nIdentity Provider"]

    subgraph Clients["MCP Clients"]
        CD["Claude Desktop"] ~~~ CC["Claude Code"] ~~~ OC["OpenClaw"]
    end

    GW["⚡ suitecrm-mcp gateway\nOAuth2 · API keys · SSE"]

    subgraph CRMs["SuiteCRM Instances"]
        C1[("CRM A")] ~~~ C2[("CRM B")] ~~~ CX[("CRM X")]
    end

    IdP -.->|"confirms identity (OAuth2 callback)"| GW
    GW -.->|"issues API key"| Clients
    Clients -->|"Bearer token"| GW
    GW -->|"Hybrid v8 GraphQL\n(v4_1 Fallback)"| CRMs

    style GW fill:#2b6cb0,stroke:#63b3ed,stroke-width:2px,color:#fff
    style IdP fill:#2d3748,stroke:#718096,color:#e2e8f0
    style CD fill:#2a4a7f,stroke:#63b3ed,stroke-width:1px,color:#ebf8ff
    style CC fill:#2a4a7f,stroke:#63b3ed,stroke-width:1px,color:#ebf8ff
    style OC fill:#2a4a7f,stroke:#63b3ed,stroke-width:1px,color:#ebf8ff
    style C1 fill:#553c9a,stroke:#b794f4,stroke-width:1px,color:#faf5ff
    style C2 fill:#553c9a,stroke:#b794f4,stroke-width:1px,color:#faf5ff
    style CX fill:#553c9a,stroke:#b794f4,stroke-width:1px,color:#faf5ff
    style Clients fill:#0d1b2e,stroke:#4299e1,stroke-width:1px,color:#90cdf4
    style CRMs fill:#1a0533,stroke:#9f7aea,stroke-width:1px,color:#d6bcfa

Users log in once via Auth0 or Azure AD; the gateway issues a personal API key. MCP clients attach it as Authorization: Bearer <key> on every request. CRM credentials never leave the gateway. Multiple CRM instances are supported - each gets its own port and tool namespace (suitecrm_crm1_*, suitecrm_crm2_*).

Smart Hybrid Routing: The gateway automatically routes basic CRUD operations and record fetching through the blazing-fast SuiteCRM 8 GraphQL API. If an AI requests a complex search requiring raw SQL filters (which GraphQL does not support), the gateway intercepts it and transparently fails over to the legacy v4.1 REST API-ensuring absolute 100% feature parity with no manual intervention.

Stateless Persistence: By moving auth sessions and user profiles from local memory/files to Redis, the gateway is completely stateless. This allows for horizontal scaling (running multiple gateway instances behind a load balancer), global rate limiting, and seamless restarts without dropping active AI connections. When running multiple instances behind a load balancer, sticky session routing is required: SSE transports and their /messages endpoint must land on the same process.

↑ back to top

📊 Observability

Ships with a complete observability stack in docker-compose.yml - one command starts everything alongside the gateway.

Alerting rules included for: circuit breaker open, high auth failure rate, latency SLO breach, session expiry storms.

mcp-admin report generates an HTML activity report from both sources - Loki supplies historical calls, SQLite covers the current period, and the two are merged automatically. Default period is daily; --period weekly and --period monthly are also supported. --serve publishes the report at /report via nginx. --user <email> drills down to a single user's calls, dry runs, and errors with module and field detail.

↑ back to top

🐳 Docker

The fastest way to run the gateway without touching Node.js or system packages. A pre-built image is published to GitHub Container Registry on every push to main.

For production, pin to a release tag such as v5.4.0 instead of floating on latest.

curl -o docker-compose.yml https://raw.githubusercontent.com/anirudhx7/suitecrm-mcp/v5.4.0/docker-compose.yml

Create your entity config (the auth service reads this to build MCP client commands):

cp entities.example.json entities.json
# edit entities.json - set endpoint, port, group for your CRM

Edit docker-compose.yml and fill in SUITECRM_ENDPOINT, AUTH0_* vars, and GATEWAY_PUBLIC_URL, then:

docker compose up -d

The gateway runs at http://localhost:3101. Visit /auth/login to authenticate and get an API key.

To update to a newer pinned release, change the image tag in docker-compose.yml and redeploy:

docker compose pull && docker compose up -d

Upgrading from pre-v5.0.0: v5.0.0 introduced a stateless Redis architecture. If you have an existing suitecrm-state named volume created by an older image, it is no longer used for SQLite. A new Redis container and volume will be provisioned automatically.

Copy

docker compose down
docker volume rm suitecrm-mcp_suitecrm-state
docker compose up -d

All persistent state (sessions, profiles) lives in this volume. Recreating it clears those files - users will need to log in again.

For self-signed CRM certificates, add NODE_TLS_REJECT_UNAUTHORIZED: "0" to the environment block. For HTTPS termination (required for OAuth in production), put a reverse proxy (nginx, Caddy) in front.

Test gateway health:

curl http://localhost:3101/health

Multi-entity with Docker

Each container handles exactly one CRM entity. For N entities, add N service blocks to docker-compose.yml, each on its own port.

services:

  suitecrm-mcp-auth:
    image: ghcr.io/anirudhx7/suitecrm-mcp:v5.4.0
    command: node auth.mjs
    working_dir: /app
    ports:
      - "127.0.0.1:3100:3100"
      - "127.0.0.1:9091:9091"   # auth metrics (Prometheus)
    environment:
      AUTH0_DOMAIN: your-tenant.auth0.com
      AUTH0_CLIENT_ID: your-client-id
      AUTH0_CLIENT_SECRET: your-client-secret
      AUTH0_AUDIENCE: https://your-api-identifier
      GATEWAY_PUBLIC_URL: https://mcp.yourdomain.com
      SESSION_TTL_DAYS: "30"
      PORT: "3100"
      METRICS_PORT: "9091"
      METRICS_BIND: "0.0.0.0"   # 0.0.0.0 required so the Prometheus container can reach it by service name
    restart: unless-stopped

  suitecrm-mcp-crm1:
    image: ghcr.io/anirudhx7/suitecrm-mcp:v5.4.0
    ports:
      - "127.0.0.1:3101:3101"   # expose via reverse proxy only
      - "127.0.0.1:9101:9090"   # entity metrics (Prometheus)
    environment:
      SUITECRM_ENDPOINT: https://crm1.example.com/legacy/service/v4_1/rest.php
      SUITECRM_PREFIX: suitecrm_crm1
      SUITECRM_CODE: crm1
      AUTH0_DOMAIN: your-tenant.auth0.com
      AUTH0_AUDIENCE: https://your-api-identifier
      REQUIRED_GROUP: crm1_users
      PORT: "3101"
      METRICS_PORT: "9090"
      METRICS_BIND: "0.0.0.0"
    depends_on:
      suitecrm-mcp-auth:
        condition: service_healthy
    restart: unless-stopped

  suitecrm-mcp-crm2:
    image: ghcr.io/anirudhx7/suitecrm-mcp:v5.4.0
    ports:
      - "127.0.0.1:3102:3102"   # expose via reverse proxy only
      - "127.0.0.1:9102:9090"   # entity metrics (Prometheus)
    environment:
      SUITECRM_ENDPOINT: https://crm2.example.com/legacy/service/v4_1/rest.php
      SUITECRM_PREFIX: suitecrm_crm2
      SUITECRM_CODE: crm2
      AUTH0_DOMAIN: your-tenant.auth0.com
      AUTH0_AUDIENCE: https://your-api-identifier
      REQUIRED_GROUP: crm2_users
      PORT: "3102"
      METRICS_PORT: "9090"
      METRICS_BIND: "0.0.0.0"
    depends_on:
      suitecrm-mcp-auth:
        condition: service_healthy
    restart: unless-stopped

What changes per entity:

• Service name (suitecrm-mcp-crm1, suitecrm-mcp-crm2, ...)
• SUITECRM_ENDPOINT - the REST API URL for that specific CRM (the path after the domain varies by SuiteCRM installation)
• SUITECRM_CODE - short identifier used in tool names and URL routing (e.g. crm1 gives tools named suitecrm_crm1_search, suitecrm_crm1_get, etc.)
• PORT and the host port mapping - each entity needs its own port (3101, 3102, ...)

What stays the same across all entities:

• AUTH0_DOMAIN and AUTH0_AUDIENCE - one Auth0 app handles all entities
• The auth service (suitecrm-mcp-auth) is shared; entity containers depend on it

Put a reverse proxy (nginx, Caddy) in front to route /crm1/ to port 3101, /crm2/ to port 3102, and /auth/ to any one instance. For production use with multiple CRMs, install.py --config entities.json handles all of this automatically on a Linux host.

↑ back to top

🔒 TLS

Gateway HTTPS (Let's Encrypt)

Pass --domain and --email to the installer to enable HTTPS on the gateway itself. The installer sets up nginx as a TLS-terminating reverse proxy and runs certbot to obtain and auto-renew a certificate.

Requirements:

• Domain must already point to this server's public IP
• Ports 80 (ACME challenge) and 443 (HTTPS) must be open

If certbot fails during install, the gateway still runs over HTTP. Fix DNS/firewall and re-run:

certbot --nginx -d your.domain.com -m you@example.com --agree-tos --redirect

Self-Signed CRM Certificates

If your SuiteCRM uses a self-signed certificate, add "tls_skip": true to the entity config (multi) or pass --tls-skip (single). This sets NODE_TLS_REJECT_UNAUTHORIZED=0.

Only use this on trusted internal networks. Never expose a TLS-skipping gateway to the public internet.

↑ back to top

🔌 Connecting a Client

Any MCP client that supports SSE transport with custom request headers will work. Each client has a different setup process - see the dedicated guide for your client:

Claude Desktop and Claude Code connect directly to the gateway URL over SSE. After installing the gateway, add the SSE endpoint and your CRM credentials to your client config. Full steps including single/multi entity configs, HTTPS variants, and verification are in the guides above.

OpenClaw uses a two-component setup: the gateway runs on a remote server (installed via install.py) and a bridge plugin runs locally on the OpenClaw machine (installed via install-bridge.py). The bridge proxies all 24 SuiteCRM tools through to the gateway. The OpenClaw guide covers both components end to end.

↑ back to top

📊 Health Checks and Monitoring

Health endpoints

# Shallow health
curl http://YOUR_SERVER:3101/health
# {"status":"ok","entity":"crm1","port":3101,"active":2,"circuit_breaker":"closed"}

# Deep health (pings CRM, returns latency)
curl http://YOUR_SERVER:3101/health/deep
# {"status":"healthy","entity":"crm1","uptime":3600,"connections":2,"circuit_breaker":"closed",
#  "checks":{"endpoint":{"status":"ok","url":"https://crm.example.com"},
#             "api":{"status":"ok","latency_ms":45},
#             "sessions":{"status":"ok","active":2}},"duration_ms":47}

/health/deep returns HTTP 200 when healthy, 503 when the CRM is unreachable. Rate-limited to 10 requests/minute.

Prometheus metrics

Two components expose Prometheus metrics on separate ports (localhost only).

# Scrape gateway metrics (single-entity systemd)
curl http://127.0.0.1:9090/metrics

# Scrape auth service metrics
curl http://127.0.0.1:9091/metrics

The included docker-compose.yml starts a Prometheus + Grafana + Loki stack that scrapes both services automatically. Set GRAFANA_PASSWORD in your environment and visit http://localhost:3000.

Two dashboards are provisioned automatically:

• suitecrm-mcp - per-entity view: 33 panels across system health, users/sessions, CRM backend, security, and tool breakdown rows
• suitecrm-mcp-fleet - multi-entity overview: all entities at a glance (circuit breaker state, connection counts, error rates, latency)

For systemd installs, add scrape targets to monitoring/prometheus.yml:

scrape_configs:
  - job_name: suitecrm-mcp-auth
    static_configs:
      - targets: ['127.0.0.1:9091']
  - job_name: suitecrm-mcp-crm1
    static_configs:
      - targets: ['127.0.0.1:9101']   # port 3101 + 6000
  - job_name: suitecrm-mcp-crm2
    static_configs:
      - targets: ['127.0.0.1:9102']   # port 3102 + 6000

Circuit breaker

The gateway tracks consecutive CRM REST API failures per entity. When the failure count reaches CIRCUIT_BREAKER_THRESHOLD (default 5), the circuit opens and all tool calls immediately return an error without hitting the CRM. After CIRCUIT_BREAKER_RESET_MS (default 60 seconds), the circuit moves to half-open and allows one probe call through. A successful probe closes the circuit; a failed probe keeps it open.

This prevents a slow or unresponsive CRM from tying up connections and causing cascading timeouts in the MCP client.

The current state appears in both /health and {prefix}_server_info tool responses.

↑ back to top

✅ Supported SuiteCRM Versions

Tested on SuiteCRM 8.8.x. Should work on any SuiteCRM version that exposes the v4_1 REST API - this has been present since early SuiteCRM releases.

Does not support SugarCRM - the APIs diverged significantly after the SuiteCRM fork.

Finding your endpoint URL

The path to the REST API varies depending on how SuiteCRM was installed. Common patterns:

https://crm.example.com/service/v4_1/rest.php
https://crm.example.com/legacy/service/v4_1/rest.php
https://crm.example.com/crm/service/v4_1/rest.php
https://crm.example.com/crm/public/legacy/service/v4_1/rest.php

To find yours: log into SuiteCRM, go to Admin → Diagnostic Tool and look at the site URL, or check with whoever manages your server. The endpoint always ends in /service/v4_1/rest.php - only the prefix before it varies. Test it with:

curl -s -X POST "https://YOUR-PATH/service/v4_1/rest.php" \
  --data 'method=get_server_info&input_type=JSON&response_type=JSON&rest_data={}'
# Should return: {"flavor":"CE","version":"...","gmt_time":"..."}

↑ back to top

🛡️ Security Notes

• HTTPS is required for production. OAuth flows and API keys must not travel over plain HTTP. Use --domain to enable Let's Encrypt, or put the gateway behind a TLS-terminating proxy.
• API keys are personal and revocable. Each user gets their own key tied to their identity. Admins can revoke a key instantly with mcp-admin revoke <sub>. Compromised keys do not expose other users.
• CRM passwords never leave the gateway. Client machines (Claude Desktop, Claude Code, OpenClaw) hold only an opaque API key. CRM credentials are stored in Redis under the crm:profiles hash on the gateway (access-controlled by Redis auth and network binding).
• Keep AUTH0_CLIENT_SECRET secret. It is stored in /etc/suitecrm-mcp/auth.env (mode 600) and only read by the auth service.
• Env files are written with mode 600 and the env directory with 700
• entities.json is in .gitignore - never commit it (it contains CRM endpoints and group names)

See SECURITY.md for full details on controls and known limitations.

↑ back to top

📄 License

MIT

📋 Prerequisites

• Ubuntu 20.04+ or Debian 11+ (the installers use apt, systemd, and nginx)
• Python 3.8+
• Root / sudo access
• Node.js is installed automatically if missing
• Redis 6.0+ (required for session and profile persistence)

↑ back to top

🔑 SuiteCRM API User Setup

Before connecting, make sure your CRM user has API access enabled:

1. Log into SuiteCRM as admin
2. Go to Admin → User Management → open the user you'll authenticate with
3. Check "Is Admin" OR set "API User" to Yes (the field name varies by SuiteCRM version)
4. Save

If API access isn't enabled, the gateway returns HTTP 401 with CRM authentication failed: Invalid Login immediately on connection - this is the most common first-run failure.

For production: create a dedicated API user with only the module permissions your AI assistant needs. Don't use the admin account.

↑ back to top

⚡ Quick Start - Single CRM

For one CRM with automatic HTTPS and OAuth login.

Requirements: Ubuntu/Debian, Python 3.8+, root access, a domain pointing to this server, OAuth app credentials (see docs/auth0-setup.md)

git clone https://github.com/anirudhx7/suitecrm-mcp.git
cd suitecrm-mcp
sudo python3 install.py \
  --url https://your-crm.example.com \
  --domain mcp.yourserver.com \
  --email you@example.com

The installer will prompt for OAuth configuration (issuer, client ID/secret, audience, gateway URL), then set up nginx, certbot, and systemd automatically.

After install, users authenticate at https://mcp.yourserver.com/auth/login to get their API key.

Test gateway health:

curl https://mcp.yourserver.com/health

Verify it's working in Claude Desktop:

After adding the MCP server config (see docs/connect-claude-desktop.md) and restarting Claude Desktop, click the hammer icon. You should see 24 tools: suitecrm_search, suitecrm_get, etc.

Try a test prompt: "List the first 5 accounts in the CRM" - Claude should call suitecrm_search automatically.

↑ back to top

🌐 Multi-Entity Install

For N CRM instances behind nginx - each gets its own port and path.

1. Copy and fill in the config:

cp entities.example.json entities.json
# Edit entities.json with your CRM endpoints and ports

2. Run the installer:

sudo python3 install.py --config entities.json

3. Enable HTTPS (recommended for production):

Pass --domain and --email. The installer updates the nginx config with your domain and runs certbot automatically.

sudo python3 install.py --config entities.json \
  --domain mcp.yourserver.com \
  --email you@example.com

The domain must already point to this server's public IP, and ports 80 and 443 must be open. After this step the gateway is available at https://mcp.yourserver.com/<code>/sse.

Once configured, the domain is saved automatically. Later --add and --remove runs preserve HTTPS without needing --domain again.

4. Open the nginx port (if using ufw, HTTP-only installs only):

sudo ufw allow 8080/tcp

5. Test a specific entity: After authenticating at /auth/login and getting an API key:

curl -s -H "Authorization: Bearer your_api_key_here" \
  http://YOUR_SERVER:8080/crm1/test
# Expected: {"success":true,"crm_user":"...","email":"...","entity":"crm1"}

6. Connect at: http://YOUR_SERVER:8080/<code>/sse (or https://your-domain/<code>/sse if HTTPS is enabled)

Verify it's working in Claude Desktop: After restarting Claude Desktop, click the hammer icon. You should see 24 tools per entity: suitecrm_crm1_search, suitecrm_crm2_search, etc.

Add entities later (no downtime on existing):

sudo python3 install.py --add --config entities.json

Remove an entity:

sudo python3 install.py --remove crm2

↑ back to top

⚙️ Configuration

Single entity - environment variables

Multi-entity - entities.json

{
  "crm1": {
    "label": "My Company CRM",
    "endpoint": "https://crm.mycompany.com/service/v4_1/rest.php",
    "port": 3101
  },
  "crm2": {
    "label": "Client B CRM",
    "endpoint": "https://crm.clientb.com/service/v4_1/rest.php",
    "port": 3102,
    "tls_skip": true
  }
}

Keys become the entity code (nginx path prefix, tool prefix suffix, service name). Ports must be unique.

↑ back to top

🔧 Troubleshooting

Check service status:

sudo python3 install.py --status

View logs:

journalctl -u suitecrm-mcp -f          # single
journalctl -u suitecrm-mcp-crm1 -f     # multi

Test gateway health:

curl https://mcp.yourserver.com/health

Common issues:

• HTTP 401 on SSE - API key invalid or expired; re-authenticate at /auth/login
• HTTP 403 on SSE - user not in the required group for this entity; check identity provider group membership
• OAuth callback error - verify OAUTH_REDIRECT_URI matches exactly what is registered in your identity provider
• CRM login failed after OAuth - CRM user not found or API access not enabled; run mcp-admin list to verify the user has a profile in Redis
• Non-JSON response - wrong CRM endpoint URL; check it ends in /service/v4_1/rest.php
• ECONNREFUSED - service isn't running; journalctl -u suitecrm-mcp
• SSE connection drops - normal for long idle periods; clients reconnect automatically

↑ back to top

⚠️ Known Limitations

LDAP / SSO users cannot authenticate via the REST API

SuiteCRM's v4_1 REST API only authenticates against local database passwords. If your organisation uses LDAP, Active Directory, or SSO, users who log into the CRM web UI via those providers will not have a local password set - and the gateway will return Invalid Login for them even with correct credentials.

Workaround: Use crm-provision-user on the CRM VM (deployed by --setup-crm-host) to set a local API password for any existing LDAP/SSO user without touching their web login. Supports single user and bulk mode via CSV.

# SSH into the CRM VM, then:

# Single user
sudo crm-provision-user john.doe secretpassword

# Bulk - CSV format: username,password
sudo crm-provision-user --csv /path/to/users.csv

This is a SuiteCRM REST API limitation, not specific to this gateway.

↑ back to top