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:

1. Create a CMS user + CiviCRM contact just for this integration.
2. Grant it the CiviCRM permissions you want exposed (access CiviCRM, view all contacts, optionally edit all contacts, authenticate with api key).
3. 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