Open Source MCP Gateway

SuiteCRM × AI Agents

The open-source MCP gateway for SuiteCRM.

Connect Claude Desktop, Claude Code, or OpenClaw to your SuiteCRM in minutes. 24 tools. OAuth2/OIDC auth. Production-ready.

View on GitHub Read the Docs
MIT License CI passing Node >=20 Redis backed 24 tools
Who It's For

Built for teams
that run on SuiteCRM.

Sales Operations

Give sales reps an AI assistant that searches, updates, and reports on CRM accounts - without exposing API credentials or requiring custom integration work.

CRM Administrators

Deploy once, control access by group. Issue and revoke API keys without touching CRM user permissions. Full audit trail included.

Internal AI Platform Teams

Add SuiteCRM as a tool in your agent stack. Multi-entity routing means one gateway serves your entire CRM fleet.

Support & Account Teams

Let support agents look up accounts, contacts, and opportunities in natural language through Claude, without CRM training or portal access.

Comparison

Why not just call
the API directly?

The SuiteCRM API works. It just puts the burden - and the risk - on every client.

Concern Direct SuiteCRM API suitecrm-mcp gateway
Auth CRM credentials on every client OAuth/OIDC login, personal API key
Tool schema Raw JSON, no descriptions 24 typed MCP tools with descriptions
Multi-client Manual per-client setup One gateway, any MCP client
API Routing Manual fallback logic in client Smart hybrid routing: SuiteCRM v8 GraphQL with v4.1 REST fallback
Key management CRM admin per user Inspect, test, issue, revoke, and flush from mcp-admin
Observability None Prometheus + Grafana + Loki
Session handling Manual login per call Redis-backed gateway sessions and CRM session renewal
Audit logging None Structured JSON, redacted
How it works

Auth in, tools out.

Three steps from login to live CRM data in Claude.

Step 1
🔐

Authenticate

Visit your gateway URL. Log in with your corporate account via Auth0 or Azure AD. Takes 30 seconds.

→
Step 2
🗝️

Get your API key

The success page shows your personal, revocable API key. CRM credentials stay server-side - you never touch them.

→
Step 3
🤖

Connect your client

Paste the key into Claude Desktop, Claude Code, or OpenClaw. 24 SuiteCRM tools load instantly.

Tools

24 tools.
Full coverage.

Every tool prefixed per entity so multiple CRMs never collide.

CRUD
search search_text get get_many create update delete count bulk_upsert get_recent
Relationships
get_relationships link_records unlink_records
Activity
log_call create_task create_note get_record_activities get_upcoming_activities get_note_attachment set_note_attachment
Introspection
get_module_fields list_modules server_info get_dropdown_values
What it does

Production-grade,
out of the box.

Everything you need to ship AI-powered CRM workflows and operate them without guessing.

🛠️

24 Tools

Full CRUD, activity logging (calls, tasks, notes), bulk operations, file attachments, dropdown introspection, and relationship management.

☁️

Redis-Backed Runtime

Auth sessions, profiles, bridge handoffs, CRM sessions, and rate limits live in Redis so restarts do not wipe state or strand users.

🔒

OAuth2/OIDC Auth

Auth0 or Azure AD. The gateway issues personal API keys. CRM credentials stay server-side - clients never touch your CRM directly.

🌐

Multi-Entity

Run N CRM instances side by side. Each gets its own port and tool namespace - suitecrm_crm1_*, suitecrm_crm2_*.

📊

Prometheus + Grafana + Loki

17 Prometheus metrics, 33-panel Grafana dashboard, Loki log aggregation, fleet overview. Alerting rules for circuit breaker, auth failures, and latency SLOs.

⚡

Circuit Breaker

Tracks CRM API failures per entity. Opens automatically at threshold, recovers with half-open probe. State visible in health and server_info.

🚀

One-Command Install

Unified install.py handles single or multi-CRM, HTTPS via Let's Encrypt, systemd, nginx - all interactive.

🧭

mcp-admin Control

List users, inspect sessions, add or remove access, test live CRM credentials, restart entities, and flush sessions from one installed operator CLI.

🔁

v8 GraphQL + v4.1 Fallback

Fast SuiteCRM v8 GraphQL for modern reads and writes, with v4.1 REST fallback for legacy routes and complex compatibility cases.

Security Model

Hardened by design.

Every layer of the auth stack is explicit. Nothing is trusted by default.

Credentials Stay Server-Side

CRM username and password are stored in the gateway profile store. Clients only hold a personal API key. No CRM secrets on user machines.

OAuth / OIDC Login

Users authenticate through your identity provider (Auth0, Azure AD, or any OIDC provider). The gateway issues a revocable personal API key on successful login.

API Keys Expire

Keys expire after 30 days by default (configurable). Admins can revoke any key immediately. Keys are scoped per user and per entity.

Redacted Audit Logs

All tool calls are logged with user sub, entity, and tool name. Sensitive fields - tokens, passwords, search strings - are redacted before writing.

Per-Entity Access Control

Group membership controls which CRM entities a user can access. No group, no connection - even with a valid API key.

Redis Runtime Block

Gateway sessions, user profiles, CRM sessions, bridge handoffs, and rate limits live in Redis so restarts do not wipe active support context.

Full observability via Prometheus metrics, Grafana dashboards, Loki log aggregation, and mcp-admin health.

Not a Black Box

Full visibility into every layer.

Most MCP gateways ship with nothing. This one includes a complete production observability stack out of the box.

📊

Prometheus

17 metrics
  • Request rate and latency histograms per entity
  • Active user and session gauges
  • CRM error codes and circuit breaker state
  • Rate-limit hits and connection rejections
  • Auth token issue, revoke, and verify counters
📈

Grafana

33-panel dashboard
  • System health, error rates, and latency panels
  • Per-user and per-session live tables
  • CRM backend health and tool breakdown rows
  • Security events and auth failure tracking
  • Fleet overview for multi-entity deployments
🪵

Loki

Structured log ingestion
  • JSON logs via Pino with per-request IDs
  • sub, email, and entity on every log line
  • Promtail tails Docker JSON logs into Loki
  • Search and filter logs in Grafana Explore using LogQL
  • Sensitive fields auto-redacted before logging

All three ship in docker-compose.yml. One command starts the full stack.
Alerting rules included for circuit breaker open, auth failures, and latency SLO breaches.

Client Support

Connect anything
MCP-compatible.

Full setup guides for every supported client.

🖥️

Claude Desktop

Add the SSE endpoint and API key to your Claude Desktop config. Single or multi-entity variants.

Setup guide →
⌨️

Claude Code

Add via claude mcp add. Works with single and multi-entity configs out of the box.

Setup guide →
🔌

OpenClaw

Two-component setup - gateway on your server, bridge plugin on the OpenClaw machine. Full guide included.

Setup guide →
Operator Control

Day-to-day support
from one CLI.

mcp-admin is installed at /usr/local/bin/mcp-admin. It gives admins a clean operating surface for users, sessions, Redis state, entity health, restarts, and emergency revocation.

User Management

  • list shows who has access and whether sessions are active.
  • whoami --email X focuses on one user and live sessions.
  • add, remove, and test cover onboarding, offboarding, and credential validation.

Login Recovery

  • revoke --email X forces a clean re-login without touching the profile.
  • sessions shows active session keys and expiry windows.
  • sessions --purge-expired clears dead Redis session entries.

Ops and Emergency

  • health, health-deep, entities, and stats make deployment checks quick.
  • restart crm1 or restart --all refreshes gateway instances after changes.
  • flush --yes-i-am-sure kills all sessions when credentials are compromised.
$ mcp-admin list
$ mcp-admin whoami --email alice@example.com
$ mcp-admin test --email alice@example.com --entity crm1
$ mcp-admin health-deep
Production Ready

Ships with everything
ops needs.

Not a prototype. A checklist of what's already in the box.

+ Docker + systemd deployment
+ mcp-admin ops CLI
+ Redis-backed sessions, profiles, bridge handoffs, and rate limits
+ SuiteCRM v8 GraphQL + v4.1 REST fallback
+ Prometheus metrics (17 metrics)
+ Grafana dashboards (33-panel entity + fleet overview)
+ Loki log aggregation
+ Prometheus alerting rules (circuit breaker, auth failures, latency SLO)
+ Circuit breaker on CRM backend
+ Per-user rate limiting
+ TLS / Let's Encrypt support
+ Multi-entity routing
+ Systemd sandboxing (NoNewPrivileges, PrivateTmp)
+ MIT license
+ Tested on SuiteCRM 8.8.x

Works with SuiteCRM v8 GraphQL where available and the v4_1 REST API for compatibility fallback.

Quick Start

Up in five minutes.

One installer. Interactive prompts handle everything else.

01
Install the gateway on your Linux server
bash
$ git clone https://github.com/Anirudhx7/suitecrm-mcp.git $ cd suitecrm-mcp $ sudo python3 install.py --domain mcp.yourcompany.com --email you@example.com

Needs Ubuntu 20.04+ with a public domain. Prompts for CRM URL, OAuth2 config, and IdP credentials. Installs Node, nginx, certbot, and systemd services automatically.

02
Users log in to get their personal API key
https://mcp.yourcompany.com/auth/login

OAuth2 login via Auth0 or Azure AD. The success page shows the exact config snippet ready to paste - no manual JSON construction needed. Keys expire in 30 days (configurable).

03
Connect your client

The entire setup is just 3 steps:

Step 1 — Install Node.js: Download from nodejs.org (if not already installed)
Step 2 — Edit claude_desktop_config.json: Add your API key from Step 02
claude_desktop_config.json
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json // Windows: %APPDATA%\Claude\claude_desktop_config.json { "mcpServers": { "suitecrm_crm1": { "command": "cmd", "args": [ "/C", "npx", "-y", "mcp-remote", "https://mcp.yourcompany.com/crm1/sse", "--transport", "sse-only", "--header", "Authorization:Bearer YOUR_API_KEY_HERE" ] } } }
Step 3 — Restart Claude Desktop: Fully quit → reopen. Done.
Full guide

Need the full setup guide?

IdP configuration, SSH provisioning, Ansible fleet deployment, Prometheus monitoring - all in one place.

View full docs

Deploy the gateway in five minutes.

One install script. Bring your own identity provider.

Read the Docs View on GitHub