CiviCRM MCP 服务器

一个全面的模型上下文协议（MCP）服务器，用于 CiviCRM，提供像 Claude Desktop 这样的AI助手直接访问您的 CiviCRM 数据和功能。

🚀 快速安装

方案 1：从 GitHub 安装

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

方案 2：从 npm 安装（如果已发布）

npm install -g civicrm-mcp-server

方案 3：克隆并构建

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

📋 先决条件

• 已安装 Node.js 18+
• 正在运行的 CiviCRM 实例（本地或可访问）
• CiviCRM API 密钥

⚙️ 配置

1. 获取 CiviCRM API 凭证

• 以管理员身份登录 CiviCRM
• 前往 联系人 → 查找您的联系人 → API 密钥 标签页
• 生成一个 API 密钥

2. 配置 Claude Desktop

在您的 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"
      }
    }
  }
}

全局安装配置路径：

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

🛠️ 可用工具

• get_contacts - 搜索并检索带有自定义字段的联系人
• create_contact - 创建新的带有自定义字段支持的联系人
• update_contact - 更新现有的包括自定义字段的联系人
• list_custom_fields - 列出任何实体类型的全部自定义字段
• get_activities - 检索带有自定义字段的活动
• create_activity - 创建新的带有自定义字段的活动
• get_contributions - 查看带有自定义字段的捐赠/贡献
• create_contribution - 记录新的带有自定义字段的捐赠
• get_events - 列出 CiviCRM 事件
• get_memberships - 查看会员资格
• system_info - 检查 CiviCRM 状态

✨ 增强的自定义字段支持

• 自动发现：自动加载并映射所有自定义字段
• 人性化名称：使用字段标签而不是技术 API 名称
• 多实体支持：适用于联系人、活动、贡献自定义字段
• 智能映射：将可读的人类字段名称转换为 API 字段名称
• 完全集成：自定义字段包含在所有获取/创建/更新操作中

💬 使用示例

基本操作

• "显示来自 Acme Corporation 的所有联系人"
• "为 Jane Doe 创建一个新的带有电子邮件 jane@example.com 的联系人"
• "列出今年超过 $1000 的所有捐款"
• "安排与联系人ID 123 的会议"

自定义字段示例

• "列出联系人的所有自定义字段"
• "显示包括其会员级别自定义字段的联系人"
• "创建一个带有自定义字段 '志愿者兴趣' 设置为 '环保' 的联系人"
• "更新联系人ID 456 并将其 '首选通信方式' 设置为 '电子邮件'"
• "查找所有带有自定义字段 '需要跟进' 设置为 '是' 的活动"
• "记录一个带有自定义字段 '活动来源' 为 '新闻通讯' 的捐赠"

🔧 开发

# 克隆仓库
git clone https://github.com/johnjacob/civicrm-mcp-server.git
cd civicrm-mcp-server

# 安装依赖
npm install

# 构建项目
npm run build

# 在开发模式下运行
npm run dev

📚 文档

参见 docs/SETUP.md 获取详细的设置说明。

🤝 贡献

1. 分叉仓库
2. 创建一个功能分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

📄 许可证

MIT 许可证 - 详情见 LICENSE 文件。

🐛 问题报告

在以下地址报告问题：https://github.com/johnjacob/civicrm-mcp-server/issues

⭐ 支持

如果您觉得这有帮助，请给这个仓库点赞！