civicrm-mcp

A Model Context Protocol server for CiviCRM. Lets any MCP-compatible client talk to a CiviCRM install through its APIv4.

Status: v0.1 — stdio transport, three tools, AuthX-first auth.

Requirements

Node.js 18.17 or later
CiviCRM 5.47 or later (tested against 5.59+)
A CiviCRM install on Drupal, WordPress, Backdrop, or Standalone

Install

npm install
npm run build

Don't have a CiviCRM yet?

See docs/INSTALL_CIVICRM.md for a 20-minute guide to running CiviCRM Standalone locally via DDEV.

Configure

Generate an API key for a dedicated "MCP Bot" contact:

Create a CMS user + CiviCRM contact just for this integration.
Grant it the CiviCRM permissions you want exposed (access CiviCRM, view all contacts, optionally edit all contacts, authenticate with api key).
On that contact's summary page → More → API Key, generate a random 20+ character key.

Copy .env.example to .env and fill in:

CIVICRM_BASE_URL=https://crm.example.org
CIVICRM_CMS=drupal            # or wordpress | standalone | backdrop
CIVICRM_API_KEY=...
CIVICRM_SITE_KEY=...          # only if the site-key guard is enabled
CIVICRM_AUTH_MODE=authx       # or legacy for pre-AuthX sites
CIVICRM_ALLOW_WRITES=false    # writes off by default
CIVICRM_ALLOW_DELETES=false   # deletes off by default

Wire up an MCP client

Any MCP-compatible client that supports stdio servers can load this. Add an entry like the one below to your client's MCP configuration file:

{
  "mcpServers": {
    "civicrm": {
      "command": "npx",
      "args": ["-y", "civicrm-mcp"],
      "env": {
        "CIVICRM_BASE_URL": "https://crm.example.org",
        "CIVICRM_CMS": "drupal",
        "CIVICRM_API_KEY": "…",
        "CIVICRM_ALLOW_WRITES": "false"
      }
    }
  }
}

Consult your client's documentation for where its MCP config file lives.

Tools

Diagnostics

Tool	What it does
`civicrm_system_info`	Connectivity / version sanity check; resolves the authenticated bot contact.

Read

Tool	What it does
`civicrm_find_contacts`	Search contacts by name or primary email.
`civicrm_get_contact`	Fetch one contact by id, with sensible default fields.
`civicrm_get_relationships`	List a contact's relationships with direction resolved.
`civicrm_get_contributions`	List contributions with filters (donor, date window, status, type) and running sum.
`civicrm_list_events`	List events (defaults to upcoming only).

Introspection

Tool	What it does
`civicrm_list_entities`	List every APIv4 entity available on the install (incl. extensions).
`civicrm_describe_entity`	Return fields + actions for an entity. Call this before `civicrm_api4` if unsure.

Write (require CIVICRM_ALLOW_WRITES=true)

Tool	What it does
`civicrm_create_contact`	Create a contact; chains email/phone creation.
`civicrm_update_contact`	Update fields on an existing contact by id.
`civicrm_log_activity`	Record an Activity (Phone Call, Meeting, Email, custom types).
`civicrm_record_contribution`	Record a donation / contribution.
`civicrm_add_to_group`	Add a contact to a group (idempotent).
`civicrm_remove_from_group`	Mark a contact as Removed from a group (preserves history).
`civicrm_register_for_event`	Register a contact for an event (Participant.create).
`civicrm_create_membership`	Create a Membership record; CiviCRM auto-calculates dates from the type.

Escape hatch

Tool	What it does
`civicrm_api4`	Generic APIv4 passthrough — any entity, any action. Gated by env flags.

Safety

Writes (create, update, save, submit) are refused unless CIVICRM_ALLOW_WRITES=true.
Deletes (delete, replace) are refused unless CIVICRM_ALLOW_DELETES=true.
api_key and hash fields are stripped from contact responses.
stdout is reserved for the MCP protocol; logs go to stderr.

Licence

MIT

civicrm-mcp

Quick Install

civicrm-mcp

Requirements

Install

Don't have a CiviCRM yet?

Configure

Wire up an MCP client

Tools

Safety

Licence

Reviews