# Suitecrm Mcp

> Open-source MCP gateway for SuiteCRM - 24 CRM tools, OAuth2/OIDC auth, multi-entity, observability.

- **Type:** MCP server
- **Install:** `agentstack add mcp-anirudhx7-suitecrm-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Anirudhx7](https://agentstack.voostack.com/s/anirudhx7)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 5.3.1
- **License:** MIT
- **Upstream author:** [Anirudhx7](https://github.com/Anirudhx7)
- **Source:** https://github.com/Anirudhx7/suitecrm-mcp
- **Website:** https://anirudh.social/suitecrm-mcp/

## Install

```sh
agentstack add mcp-anirudhx7-suitecrm-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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, AOS_Quotes, AOS_Invoices, AOS_Products, AOS_Contracts, AOR_Reports, AOW_WorkFlow, SecurityGroups - and any custom modules in your instance.

↑ back to top

---

## 🏗️ 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 ` 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))

```bash
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:**
```bash
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:**
```bash
cp entities.example.json entities.json
# Edit entities.json with your CRM endpoints and ports
```

**2. Run the installer:**
```bash
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.

```bash
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):
```bash
sudo ufw allow 8080/tcp
```

**5. Test a specific entity:**
After authenticating at `/auth/login` and getting an API key:
```bash
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):**
```bash
sudo python3 install.py --add --config entities.json
```

**Remove an entity:**
```bash
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`.

```bash
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):

```bash
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:

```bash
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:
```bash
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](https://github.com/Anirudhx7)
- **Source:** [Anirudhx7/suitecrm-mcp](https://github.com/Anirudhx7/suitecrm-mcp)
- **License:** MIT
- **Homepage:** https://anirudh.social/suitecrm-mcp/

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v5.3.1 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **5.3.1** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-anirudhx7-suitecrm-mcp
- Seller: https://agentstack.voostack.com/s/anirudhx7
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.