Skip to content

CiviCRM MCP Server

Pre-release

There is no public release yet, though the code has already run on a production site. Pages marked planned describe how the first release will work. See the Roadmap.

CiviCRM MCP Server (civicrm_mcp) lets an AI assistant, such as Claude or ChatGPT, answer questions from your CiviCRM data. It uses the Model Context Protocol (MCP), an open standard for connecting AI clients to data sources.

  • It runs inside CiviCRM. It is an ordinary extension, not a separate server: it answers at the civicrm/mcp route, one ordinary PHP request at a time, with nothing kept running between requests. There is no Node process to host and no API key held by an outside program, so it works on the PHP-only managed hosting many small nonprofits use. It runs on WordPress and CiviCRM Standalone.
  • It acts as a real person. Each AI conversation is signed in as a CiviCRM user, and the built-in tools check every request against that user's CiviCRM permissions. See Security and permissions for the details and the one exception.
  • Administrators decide who connects, and with what. A permission profile gives each person a set of tools and entities, and can only take access away, never add it. Everything is set up on screens in the CiviCRM menu, with a setup checklist; no command line is needed. See Setup.
  • Every tool call is logged, refused ones included: who, which tool, what was asked and how many rows came back. See Security § The call log.
  • It has its own small OAuth 2.1 sign-in, so people sign in with their normal CMS login, the same "sign in with…" flow they already know. That means it can be added to web-based AI clients such as Claude and ChatGPT as a connector. The tokens it issues work only on the MCP route, never on the rest of CiviCRM's API.
  • It starts with two read-only tools: one describes the data, one reads it, across ten entities (Contact, Activity, Case, Contribution, Membership, Event, Participant, Relationship, CaseContact and ActivityContact). See Built-in tools. Writes are a possible later, opt-in addition (Roadmap; Scope).
  • Other extensions can add tools by listening to an event, a bit like WordPress's Abilities API, including tools backed by SearchKit displays an administrator builds. See Adding your own tools.

Who it is for

CiviCRM administrators at nonprofits who want staff to ask questions such as "which contacts donated this year?" or "what has happened on this case?" in plain language, without building a report for each question, and without handing an AI tool a key to the whole database.

Where to start

These pages are grouped by who they are for, in the menu on the left.

Feedback

We want to hear from you, especially while the extension is young. Questions, bug reports and ideas for improvement are all welcome, and none is too small. If something in these pages was unclear, that is worth reporting too.

Open a work item on the issue tracker (you need a free lab.civicrm.org account). For a bug, say which CiviCRM version and CMS you use and what you did, and leave out any real contact data.

A security problem is the exception: do not report it in public. Follow the security policy instead.

Life cycle

This extension is maintained part-time by a group of volunteers, not by a company. There is no paid support. We aim to reply to new issues within 7 days, but we cannot promise a fix. Read the Release Notes before every upgrade.