1. Conduid
  2. Science
  3. io.github.YogiAdhik/civicrm-mcp
MCP server · Science

io.github.YogiAdhik/civicrm-mcp

· github.com/YogiAdhik/civicrm-mcp

Model Context Protocol server for CiviCRM — AuthX-first, schema-introspected, write-gated.

Unclaimed science
InstallView source
37Low

Scored 5 months ago · breakdown

About io.github.YogiAdhik/civicrm-mcp

io.github.YogiAdhik/civicrm-mcp is an MCP server in the Science category: model Context Protocol server for CiviCRM — AuthX-first, schema-introspected, write-gated.

Install

Claude Code
claude mcp add io-github-yogiadhik-civicrm-mcp -- npx -y civicrm-mcp
npx
npx -y civicrm-mcp

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Tools (2)

civicrm_system_infoConnectivity / version sanity check; resolves the authenticated bot contact.

Parameters not published.

civicrm_whoamiResolves the bot contact and probes which entities it can read. Use this first when setting up.

Parameters not published.

Ask AI

✦

Ask AI about io.github.YogiAdhik/civicrm-mcp

Powered by Claude · Grounded in docs

I know everything about io.github.YogiAdhik/civicrm-mcp. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

  • ✓README presentThe repository ships documentation.

5 checks have not been run yet.

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:

  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

README copy captured when this server was indexed; it may lag the repository. The original is authoritative.

Questions

About io.github.YogiAdhik/civicrm-mcp

How do I install io.github.YogiAdhik/civicrm-mcp?

Run claude mcp add io-github-yogiadhik-civicrm-mcp -- npx -y civicrm-mcp, then add the server to your MCP client's configuration.

Is io.github.YogiAdhik/civicrm-mcp safe to use with an AI agent?

Its trust score is 37 out of 100 (low). It passes 1 of the 1 static security checks run so far. It has no ConduID identity yet, so agent calls to it are not receipted.

Is io.github.YogiAdhik/civicrm-mcp still maintained?

Conduid hasn't recorded a commit date for this repository yet. Check the repository directly for recent activity.