civicrm

This MCP server integrates CiviCRM with AI assistants, enabling the assistant to access CiviCRM data and perform common CRM tasks through a collaborative, natural-language interface. It exposes a suite of tools that let you search, create, update, and retrieve records for Contacts, Activities, Contributions, Events, and Memberships, while also handling custom fields automatically. Tools like get_contacts, create_contact, update_contact, and list_custom_fields provide structured API interactions behind a friendly prompt layer, so you can ask questions like “Show me all contacts from Acme Corporation” or “Create a contact with a custom field for Volunteer Interest.” The server also supports system_info, which can report on the CiviCRM status, enabling health checks during conversations with the AI assistant. Enhanced custom field support means human-friendly field names and automatic mapping, so you can reference fields by their labels rather than API keys, and still have changes applied reliably across entities.

To use the MCP server, configure Claude Desktop (or your MCP client) with the civicrm entry from your claude_desktop_config.json, providing the base URL of your CiviCRM instance and an API key. Once configured, you can issue natural language requests that are translated into CiviCRM API calls by the MCP server, including operations that involve custom fields. Examples include listing contacts with a specific custom field, creating or updating records with custom fields, and retrieving event or donation data. The included tooling ensures operations respect CiviCRM’s data model while presenting a user-friendly interface for day-to-day CRM tasks.

Prerequisites:

• Node.js 18+ installed
• Access to a running CiviCRM instance
• A CiviCRM API key

Install from GitHub (recommended):

1. Install globally

npm install -g git+https://github.com/johnjacob/civicrm-mcp-server.git

Install from npm (if published):

npm install -g civicrm-mcp-server

Clone and build (optional but useful for local development):

git clone https://github.com/johnjacob/civicrm-mcp-server.git
cd civicrm-mcp-server
npm install
npm run build

Configure Claude Desktop (example):

1. Obtain CiviCRM API credentials as described in the README.
2. Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "civicrm": {
      "command": "civicrm-mcp-server",
      "env": {
        "CIVICRM_BASE_URL": "https://your-civicrm-site.com",
        "CIVICRM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Run the server (example if installed globally):

# If the binary is available on PATH after installation
civicrm-mcp-server

If you built locally, start the server via your usual Node.js run script (e.g., npm run dev or npm start, depending on your environment).

Environment variables:

• CIVICRM_BASE_URL: Base URL of your CiviCRM instance (e.g., https://crm.example.com)
• CIVICRM_API_KEY: API key with appropriate permissions for the operations you intend to perform

Tips:

• Ensure CiviCRM is accessible from the environment running the MCP server (consider firewall and network access).
• The server automatically discovers and maps custom fields; reference them by their human-friendly labels in prompts.
• Use system_info to verify connectivity before performing write operations.
• If you encounter authentication or permission issues, double-check the API key scope and the CiviCRM URL in your config.