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.