johncallhub/civicrm-mcp-server

CiviCRM MCP Server

A comprehensive Model Context Protocol (MCP) server for CiviCRM that provides AI assistants like Claude Desktop with direct access to your CiviCRM data and functionality.

🚀 Quick Install

Option 1: Install from GitHub

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

Option 2: Install from npm (if published)

npm install -g civicrm-mcp-server

Option 3: Clone and Build

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

📋 Prerequisites

• Node.js 18+ installed
• A running CiviCRM instance (local or accessible)
• CiviCRM API key

⚙️ Configuration

1. Get CiviCRM API Credentials

• Log into CiviCRM as administrator
• Go to Contacts → Find your contact → API Key tab
• Generate an API key

2. Configure Claude Desktop

Add to your 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"
      }
    }
  }
}

Global install config path:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

🛠️ Available Tools

• get_contacts - Search and retrieve contacts with custom fields
• create_contact - Create new contacts with custom field support
• update_contact - Update existing contacts including custom fields
• list_custom_fields - List all custom fields for any entity type
• get_activities - Retrieve activities with custom fields
• create_activity - Create new activities with custom fields
• get_contributions - View donations/contributions with custom fields
• create_contribution - Record new donations with custom fields
• get_events - List CiviCRM events
• get_memberships - View memberships
• system_info - Check CiviCRM status

✨ Enhanced Custom Field Support

• Automatic Discovery: Automatically loads and maps all custom fields
• Human-Friendly Names: Use field labels instead of technical API names
• Multiple Entity Support: Works with Contact, Activity, Contribution custom fields
• Smart Mapping: Converts human-readable field names to API field names
• Complete Integration: Custom fields included in all get/create/update operations

💬 Usage Examples

Basic Operations

• "Show me all contacts from Acme Corporation"
• "Create a new contact for Jane Doe with email jane@example.com"
• "List all donations over $1000 from this year"
• "Schedule a meeting with contact ID 123"

Custom Field Examples

• "List all custom fields for contacts"
• "Show me contacts including their membership level custom field"
• "Create a contact with custom field 'Volunteer Interest' set to 'Environmental'"
• "Update contact ID 456 and set their 'Preferred Communication' to 'Email'"
• "Find all activities with custom field 'Follow-up Required' set to 'Yes'"
• "Record a donation with custom field 'Campaign Source' as 'Newsletter'"

🔧 Development

# Clone the repository
git clone https://github.com/johnjacob/civicrm-mcp-server.git
cd civicrm-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

📚 Documentation

See for detailed setup instructions.

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

📄 License

MIT License - see file for details.

🐛 Issues

Report issues at: https://github.com/johnjacob/civicrm-mcp-server/issues

⭐ Support

If this helps you, please star the repository!