suitecrm-mcp

# <a name="top"></a>suitecrm-mcp

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

[![Live Docs](https://img.shields.io/badge/Docs-Live-orange?style=flat-square)](https://anirudh.social/suitecrm-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Anirudhx7/suitecrm-mcp/blob/main/LICENSE)
[![GitHub Release](https://img.shields.io/github/v/release/Anirudhx7/suitecrm-mcp?color=369eff&labelColor=black&logo=github&style=flat-square)](https://github.com/Anirudhx7/suitecrm-mcp/releases)
[![CI](https://img.shields.io/github/actions/workflow/status/Anirudhx7/suitecrm-mcp/ci.yml?style=flat-square&label=CI&labelColor=black)](https://github.com/Anirudhx7/suitecrm-mcp/actions/workflows/ci.yml)
[![GitHub Stars](https://img.shields.io/github/stars/Anirudhx7/suitecrm-mcp?style=social)](https://github.com/Anirudhx7/suitecrm-mcp)
[![Issues](https://img.shields.io/github/issues/Anirudhx7/suitecrm-mcp?color=ff80eb&labelColor=black&style=flat-square)](https://github.com/Anirudhx7/suitecrm-mcp/issues)
[![LinkedIn](https://img.shields.io/badge/LinkedIn-Anirudh%20Mehandru-0077B5?style=flat-square&logo=linkedin&logoColor=white)](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.

<!--
![Demo: Asking Claude to create a Lead in SuiteCRM](docs/assets/demo-placeholder.gif)
*(Replace this with a 60-second Loom/GIF showing Claude creating a record in SuiteCRM)*
-->

---

## 🚀 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) |

---

## <a name="features"></a>✨ 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

<p align="right"><a href="#top">↑ back to top</a></p>

---

## <a name="tools"></a>🛠️ 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, AOS_Quotes, AOS_Invoices, AOS_Products, AOS_Contracts, AOR_Reports, AOW_WorkFlow, SecurityGroups - and any custom modules in your instance.

<p align="right"><a href="#top">↑ back to top</a></p>

---

## <a name="architecture"></a>🏗️ Architecture

```mermaid
%%{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.

<p align="right"><a href="#top">↑ back to top</a></p>

---

## <a name="observability"></a>📊 Observability

Ships with