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/mcproute, 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.
- Administrators: read Security and permissions first. It sets out exactly what an AI client can reach. Then install the extension and work through Setup. Built-in tools describes the two tools you can give people.
- Staff who will connect: follow Connect your AI client, with the two values your administrator gives you, then see Asking questions. FAQs covers what the AI can see and what to check if sign-in fails.
- Developers: Adding your own tools shows how your own extension adds tools for your site. Publishing a SearchKit display is the rule for a tool that shows more than a user's own permissions, and Testing your tools covers checking them.
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.