Suitecrm Mcp

suitecrm-mcp

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

[](https://anirudh.social/suitecrm-mcp/) [](https://github.com/Anirudhx7/suitecrm-mcp/blob/main/LICENSE) [](https://github.com/Anirudhx7/suitecrm-mcp/releases) [](https://github.com/Anirudhx7/suitecrm-mcp/actions/workflows/ci.yml) [](https://github.com/Anirudhx7/suitecrm-mcp) [](https://github.com/Anirudhx7/suitecrm-mcp/issues) [](https://www.linkedin.com/in/anirudh-mehandru/)

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?

| Feature | SuiteCRM-MCP (Open Source) | Commercial Alternatives | |---------|:---:|:---:| | Price | Free Forever | $1,000s / Year | | Capabilities | Full CRUD (24+ tools) | Often Read-Only / Limited | | Data Privacy | 100% Self-Hosted | Third-party Cloud/SaaS | | Complexity | 5-Min Setup | Sales calls & Long trials | | Observability | Full Grafana/Prometheus | Minimal / Closed |

---

🛡️ 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

| | Section | |---|---| | ✨ | [Features](#features) | | 🛠️ | [Tools](#tools) | | 🏗️ | [Architecture](#architecture) | | 📊 | [Observability](#observability) | | 📋 | [Prerequisites](#prerequisites) | | 🔑 | [SuiteCRM API User Setup](#suitecrm-api-user-setup) | | ⚡ | [Quick Start - Single CRM](#quick-start---single-crm) | | 🌐 | [Multi-Entity Install](#multi-entity-install) | | 🐳 | [Docker](#docker) | | ⚙️ | [Configuration](#configuration) | | 🔒 | [TLS](#tls) | | 🔌 | [Connecting a Client](#connecting-a-client) | | 📊 | [Health Checks and Monitoring](#health-checks-and-monitoring) | | 🔧 | [Troubleshooting](#troubleshooting) | | ✅ | [Supported SuiteCRM Versions](#supported-suitecrm-versions) | | ⚠️ | [Known Limitations](#known-limitations) | | 🛡️ | [Security Notes](#security-notes) | | 📄 | [License](#license) |

---

✨ 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

| Tool | Description | |------|-------------| | {prefix}_search | Search records using SQL WHERE clause | | {prefix}_search_text | Full-text search across modules | | {prefix}_get | Get a single record by UUID | | {prefix}_get_many | Fetch up to 100 records by ID list in one call | | {prefix}_create | Create a new record | | {prefix}_update | Update an existing record | | {prefix}_delete | Soft-delete a record | | {prefix}_count | Count records matching a query | | {prefix}_bulk_upsert | Create or update up to 100 records at once | | {prefix}_get_relationships | Get related records via a link field | | {prefix}_link_records | Create a relationship between records | | {prefix}_unlink_records | Remove a relationship | | {prefix}_get_module_fields | Get field definitions for a module | | {prefix}_get_dropdown_values | List all dropdowns or get key→label values for one | | {prefix}_list_modules | List all available CRM modules | | {prefix}_get_recent | Get recently viewed records for the current user | | {prefix}_get_upcoming_activities | Get upcoming calls, meetings, and tasks | | {prefix}_get_record_activities | Get activity history for any record | | {prefix}_log_call | Create a call and link it to contacts/accounts | | {prefix}_create_task | Create a task with optional parent record link | | {prefix}_create_note | Create a note linked to a parent record | | {prefix}_get_note_attachment | Download a file attachment from a Notes record | | {prefix}_set_note_attachment | Upload a file attachment to a Notes record | | {prefix}_server_info | Gateway status and connection info |

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

Supported modules include: Accounts, Contacts, Leads, Opportunities, Cases, Calls, Meetings, Tasks, Notes, Emails, Documents, Campaigns, AOSQuotes, AOSInvoices, AOSProducts, AOSContracts, AORReports, AOWWorkFlow, 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 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.

| Component | What you get | |-----------|-------------| | Prometheus | 17 metrics: request rate, latency histograms per entity, active sessions, CRM error codes, circuit breaker state, rate-limit hits, auth counters | | Grafana | 33-panel entity dashboard (system health, user/session tables, CRM backend, security, tool breakdown) + fleet overview dashboard for multi-entity. Query structured logs and metrics side-by-side in Grafana Explore. | | Loki | Structured JSON log ingestion via Promtail - search and filter logs by user, entity, or request ID directly in Grafana Explore using LogQL, queryable alongside metrics. Non-PII fields (status, stage, type, dates) log actual values; sensitive fields (names, emails, search queries) are always redacted. |

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 drills down to a single user's calls, dry runs, and errors with module and field detail.

↑ back to top

---

📋 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](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](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//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//sse (or https://your-domain//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

---

🐳 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. > ``bash > 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 terminatio

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Anirudhx7
• Source: Anirudhx7/suitecrm-mcp
• License: MIT
• Homepage: https://anirudh.social/suitecrm-mcp/

Install and usage instructions live in the source repository linked above.