Civicrm Mcp
Wires Claude or any MCP client to a CiviCRM instance via APIv4, with typed tools for contacts, contributions, events, and relationships. Authentication is AuthX first, with API key fallback. Writes and deletes are gated behind explicit env flags, and dry run mode lets you validate behavior before going live. You get introspection tools to explore entities and fields, plus the ability to run admin-built SavedSearches. The generic api4 passthrough exists but ships disabled. Reach for this if you're building agent workflows that need to read donor records, log activities, or register event participants without writing raw API calls.
- tools
- 25
- auth
- Secret needed
- transport
- STDIO
- env vars
- 7
- last updated
- Apr 24, 2026
Tools
25 toolsPublic tool metadata for what this MCP can expose to an agent.
civicrm_system_infoConnectivity / version sanity check; resolves the authenticated bot contact.
Connectivity / version sanity check; resolves the authenticated bot contact.
No parameter schema in public metadata yet.
civicrm_whoamiResolves the bot contact and probes which entities it can read. Use this first when setting up.
Resolves the bot contact and probes which entities it can read. Use this first when setting up.
No parameter schema in public metadata yet.
civicrm_find_contactsSearch contacts by name or primary email.
Search contacts by name or primary email.
No parameter schema in public metadata yet.
civicrm_get_contactFetch one contact by id, with sensible default fields.
Fetch one contact by id, with sensible default fields.
No parameter schema in public metadata yet.
civicrm_get_relationshipsList a contact's relationships with direction resolved.
List a contact's relationships with direction resolved.
No parameter schema in public metadata yet.
civicrm_get_contributionsList contributions with filters (donor, date window, status, type) and running sum.
List contributions with filters (donor, date window, status, type) and running sum.
No parameter schema in public metadata yet.
civicrm_list_eventsList events (defaults to upcoming only).
List events (defaults to upcoming only).
No parameter schema in public metadata yet.
civicrm_list_saved_searchesDiscover SearchKit SavedSearches the admin has built.
Discover SearchKit SavedSearches the admin has built.
No parameter schema in public metadata yet.
civicrm_run_saved_searchExecute a SavedSearch by name via SearchDisplay.run. Safest way to run complex queries.
Execute a SavedSearch by name via SearchDisplay.run. Safest way to run complex queries.
No parameter schema in public metadata yet.
civicrm_list_entitiesList every APIv4 entity available on the install (incl. extensions).
List every APIv4 entity available on the install (incl. extensions).
No parameter schema in public metadata yet.
civicrm_describe_entityReturn fields + actions for an entity. Call this before civicrm_api4 if unsure.
Return fields + actions for an entity. Call this before civicrm_api4 if unsure.
No parameter schema in public metadata yet.
civicrm_describe_field_optionsReturn the option list (enum values) for one field — cheaper than a full entity describe.
Return the option list (enum values) for one field — cheaper than a full entity describe.
No parameter schema in public metadata yet.
civicrm_create_contactCreate a contact; chains email/phone creation.
Create a contact; chains email/phone creation.
No parameter schema in public metadata yet.
civicrm_update_contactUpdate fields on an existing contact by id.
Update fields on an existing contact by id.
No parameter schema in public metadata yet.
civicrm_log_activityRecord an Activity (Phone Call, Meeting, Email, custom types).
Record an Activity (Phone Call, Meeting, Email, custom types).
No parameter schema in public metadata yet.
civicrm_record_contributionRecord a donation / contribution.
Record a donation / contribution.
No parameter schema in public metadata yet.
civicrm_add_to_groupAdd a contact to a group (idempotent).
Add a contact to a group (idempotent).
No parameter schema in public metadata yet.
civicrm_remove_from_groupMark a contact as Removed from a group (preserves history).
Mark a contact as Removed from a group (preserves history).
No parameter schema in public metadata yet.
civicrm_register_for_eventRegister a contact for an event (Participant.create).
Register a contact for an event (Participant.create).
No parameter schema in public metadata yet.
civicrm_create_membershipCreate a Membership record; CiviCRM auto-calculates dates from the type.
Create a Membership record; CiviCRM auto-calculates dates from the type.
No parameter schema in public metadata yet.
civicrm_add_noteAttach a free-text Note to a contact, contribution, activity, case, or relationship.
Attach a free-text Note to a contact, contribution, activity, case, or relationship.
No parameter schema in public metadata yet.
civicrm_tag_contactsAdd a tag to up to 500 contacts in one call (idempotent).
Add a tag to up to 500 contacts in one call (idempotent).
No parameter schema in public metadata yet.
civicrm_untag_contactsRemove a tag from contacts. Also requires CIVICRM_ALLOW_DELETES=true.
Remove a tag from contacts. Also requires CIVICRM_ALLOW_DELETES=true.
No parameter schema in public metadata yet.
civicrm_send_contribution_receiptTrigger (or re-send) the standard receipt email for a contribution.
Trigger (or re-send) the standard receipt email for a contribution.
No parameter schema in public metadata yet.
civicrm_api4Generic APIv4 passthrough — any entity, any action. Off unless CIVICRM_ALLOW_GENERIC_API=true.
Generic APIv4 passthrough — any entity, any action. Off unless CIVICRM_ALLOW_GENERIC_API=true.
No parameter schema in public metadata yet.
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageConfiguration
CIVICRM_BASE_URL*Base URL of the CiviCRM install, e.g. https://crm.example.org. No trailing slash.
CIVICRM_API_KEY*secretAPI key of the contact the server authenticates as. Keep it on a dedicated 'MCP Bot' contact with minimum permissions.
CIVICRM_CMSdefault: drupalCMS host: drupal, wordpress, standalone, or backdrop.
CIVICRM_SITE_KEYsecretOptional — only needed if the site enables the AuthX site-key guard.
CIVICRM_AUTH_MODEdefault: authxauthx (default, recommended) or legacy for pre-5.36 installs.
CIVICRM_ALLOW_WRITESdefault: falseSet to 'true' to enable create / update / save / submit actions. Off by default.
CIVICRM_ALLOW_DELETESdefault: falseSet to 'true' to enable delete / replace actions. Off by default.
Readme
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, optionallyedit 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:
Details
- Repository
- github.com/yogiadhik/civicrm-mcp
- Package
civicrm-mcp- Transport
- STDIO
- Auth
- Required
- Registry
- MCP registry, active