civicrm-mcp

civicrm-mcp

A Model Context Protocol server for CiviCRM. Lets Claude Desktop, Claude Code, and other MCP-compatible clients 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

Use with Claude Desktop / Code

Add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json or the equivalent for Claude Code):

{
  "mcpServers": {
    "civicrm": {
      "command": "node",
      "args": ["/absolute/path/to/civicrm-mcp/dist/index.js"],
      "env": {
        "CIVICRM_BASE_URL": "https://crm.example.org",
        "CIVICRM_CMS": "drupal",
        "CIVICRM_API_KEY": "…",
        "CIVICRM_ALLOW_WRITES": "false"
      }
    }
  }
}

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