内容
# everything-civi
用于完整CiviCRM操作的MCP服务器。 将任何AI助手连接到您的CiviCRM实例 - 通过单个集成管理联系人、贡献、会员资格、事件、案例和所有150多个实体。
## 功能
- **28种工具**，涵盖CRUD、发现、工作流程、SearchKit、批量操作和管理
- **3个MCP提示**，用于指导CiviCRM管理、数据导入和报告
- **3种资源**，包含查询构造指南和实时实体列表
- 与任何CiviCRM 5.x实例（WordPress、Drupal、Joomla、独立）兼容
- 与Claude、OpenAI、Gemini、Cursor、VS Code和任何MCP客户端兼容
- 暂时错误重试，指数退避
- 速率限制，保护您的CiviCRM实例
- 结构化JSON审计日志，包含PII保护
- 工具权限允许列表，用于访问控制
- 142个测试（单元+集成）
## 快速开始
### 先决条件
- Python 3.11+
- 具有API密钥访问权限的CiviCRM实例
- [uv](https://docs.astral.sh/uv/)（推荐）或pip
### 安装
```bash
git clone https://github.com/ananda-callhub/everything-civi.git
cd everything-civi
uv venv --python 3.12
source .venv/bin/activate
uv pip install -e .
```
### 配置
复制示例环境文件并填写您的CiviCRM凭证：
```bash
cp .env.example .env
```
```env
CIVICRM_BASE_URL=https://your-civicrm-site.org
CIVICRM_API_KEY=your-api-key-here
CIVICRM_VERIFY_SSL=true
CIVICRM_TIMEOUT=30
CIVICRM_MAX_RETRIES=2
CIVICRM_RETRY_DELAY=1.0
CIVICRM_MAX_CONCURRENT=5
CIVICRM_LOG_LEVEL=INFO
CIVICRM_AUDIT_LOG=true
CIVICRM_ALLOWED_TOOLS=
```
要在CiviCRM中生成API密钥：前往 **联系人 > 您的管理员联系人 > API密钥**，或运行：
```bash
cv api4 Contact.update '{"where":[["id","=",YOUR_CONTACT_ID]],"values":{"api_key":"your-key-here"}}'
```
### 运行
```bash
everything-civi
```
### 与Claude Desktop一起使用
将以下内容添加到您的Claude Desktop配置（`~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"everything-civi": {
"command": "/path/to/everything-civi/.venv/bin/everything-civi",
"env": {
"CIVICRM_BASE_URL": "https://your-civicrm-site.org",
"CIVICRM_API_KEY": "your-api-key-here"
}
}
}
}
```
### 与Claude Code一起使用
将以下内容添加到您的项目的`.mcp.json`：
```json
{
"mcpServers": {
"everything-civi": {
"command": "/path/to/everything-civi/.venv/bin/everything-civi",
"env": {
"CIVICRM_BASE_URL": "https://your-civicrm-site.org",
"CIVICRM_API_KEY": "your-api-key-here"
}
}
}
}
```
### 与OpenAI Agents SDK一起使用
```python
from agents import Agent
from agents.mcp import MCPServerStdio
async with MCPServerStdio(
command="everything-civi",
env={
"CIVICRM_BASE_URL": "https://your-civicrm-site.org",
"CIVICRM_API_KEY": "your-api-key-here",
},
) as mcp:
agent = Agent(name="CiviCRM Assistant", mcp_servers=[mcp])
```
### 与Cursor一起使用
将以下内容添加到您的Cursor MCP配置（`.cursor/mcp.json`）：
```json
{
"mcpServers": {
"everything-civi": {
"command": "/path/to/everything-civi/.venv/bin/everything-civi",
"env": {
"CIVICRM_BASE_URL": "https://your-civicrm-site.org",
"CIVICRM_API_KEY": "your-api-key-here"
}
}
}
}
```
### 与VS Code / GitHub Copilot一起使用
将以下内容添加到您的VS Code设置（`.vscode/settings.json`）：
```json
{
"mcp": {
"servers": {
"everything-civi": {
"command": "/path/to/everything-civi/.venv/bin/everything-civi",
"env": {
"CIVICRM_BASE_URL": "https://your-civicrm-site.org",
"CIVICRM_API_KEY": "your-api-key-here"
}
}
}
}
}
```
### 与Gemini CLI一起使用
将以下内容添加到您的Gemini CLI设置（`~/.gemini/settings.json`）：
```json
{
"mcpServers": {
"everything-civi": {
"command": "/path/to/everything-civi/.venv/bin/everything-civi",
"env": {
"CIVICRM_BASE_URL": "https://your-civicrm-site.org",
"CIVICRM_API_KEY": "your-api-key-here"
}
}
}
}
```
### 使用MCP Inspector验证
使用官方MCP Inspector交互式测试您的服务器：
```bash
npx @anthropic-ai/mcp-inspector everything-civi
```
## 工具
### CRUD（6种工具）
适用于CiviCRM所有150多个实体的通用工具。
| 工具 | 描述 |
|------|-------------|
| `civicrm_get` | 查询任何实体，支持筛选、连接、聚合和分页 |
| `civicrm_create` | 创建任何实体的单个记录 |
| `civicrm_update` | 更新匹配WHERE子句的记录 |
| `civicrm_delete` | 删除记录（默认为软删除） |
| `civicrm_save` | 批量创建或更新（UPSERT），匹配字段 |
| `civicrm_replace` | 原子替换一组子记录 |
### 发现（5种工具）
在运行时内省CiviCRM模式。
| 工具 | 描述 |
|------|-------------|
| `civicrm_list_entities` | 列出实例上可用的所有实体 |
| `civicrm_describe_entity` | 获取实体的完整字段模式、类型、选项和操作 |
| `civicrm_explore_options` | 列出字段的所有有效选项值 |
| `civicrm_check_access` | 检查实体/操作的API用户权限 |
| `civicrm_find_relationships` | 发现实体之间的外键关系 |
### 工作流程（9种工具）
更高级别的操作，链接多个API调用，支持名称解析和验证。
| 工具 | 描述 |
|------|-------------|
| `civicrm_search_contacts` | 跨姓名、电子邮件和电话的智能搜索，返回丰富的结果 |
| `civicrm_record_contribution` | 记录捐款/付款，解析财务类型 |
| `civicrm_manage_membership` | 创建、续期或取消会员资格，具备状态感知逻辑 |
| `civicrm_register_for_event` | 注册联系人参加事件，支持可选付款 |
| `civicrm_log_activity` | 记录活动，具备正确的源/目标/联系人角色 |
| `civicrm_manage_group_contacts` | 添加或删除联系人到群组（保留历史记录） |
| `civicrm_manage_relationship` | 创建或禁用联系人之间的关系 |
| `civicrm_open_case` | 打开案例，自动链接联系人 |
| `civicrm_add_tags` | 为联系人或其他实体添加标签，自动创建缺失的标签 |
### SearchKit（3种工具）
执行通过SearchKit UI创建的CiviCRM保存的搜索。
| 工具 | 描述 |
|------|-------------|
| `civicrm_list_saved_searches` | 列出实例上的所有保存的搜索 |
| `civicrm_run_saved_search` | 执行保存的搜索，支持运行时筛选 |
| `civicrm_describe_saved_search` | 获取搜索定义和可用显示 |
### 实用工具（3种工具）
批量操作和智能助手。
| 工具 | 描述 |
|------|-------------|
| `civicrm_paginate` | 自动分页浏览大型结果集，设置安全上限 |
| `civicrm_bulk_import` | 批量导入记录，支持UPSERT和每批次错误恢复 |
| `civicrm_find_or_create_contact` | 按电子邮件/ID查找现有联系人或创建 |
### 管理（2种工具）
服务器健康和维护。
| 工具 | 描述 |
|------|-------------|
| `civicrm_system_status` | 检查CiviCRM连接性、版本和健康警告 |
| `civicrm_system_flush` | 清除所有CiviCRM缓存 |
## 提示
| 提示 | 描述 |
|--------|-------------|
| `civicrm_admin` | 用于通用CiviCRM管理的系统提示 |
| `civicrm_data_import` | 用于导入数据的引导工作流程，支持验证和重复数据清理 |
| `civicrm_reporting` | 查询构造和数据分析模式 |
## 资源
| URI | 描述 |
|-----|-------------|
| `civicrm://guide/querying` | 完整的APIv4查询参考（WHERE运算符、连接、聚合） |
| `civicrm://guide/entities` | 跨所有CiviCRM域的实体关系概述 |
| `civicrm://entities` | 连接实例的实时实体列表 |
## 配置
所有设置均通过环境变量配置，前缀为`CIVICRM_`：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `CIVICRM_BASE_URL` | （必填） | 您的CiviCRM实例URL |
| `CIVICRM_API_KEY` | （必填） | 身份验证的API密钥 |
| `CIVICRM_VERIFY_SSL` | `true` | 验证SSL证书 |
| `CIVICRM_TIMEOUT` | `30` | 请求超时（秒） |
| `CIVICRM_MAX_RETRIES` | `2` | 暂时错误重试（5xx，超时） |
| `CIVICRM_RETRY_DELAY` | `1.0` | 指数退避的基准延迟（秒） |
| `CIVICRM_MAX_CONCURRENT` | `5` | 最大并发API请求 |
| `CIVICRM_LOG_LEVEL` | `INFO` | 日志级别（DEBUG，INFO，WARNING，ERROR） |
| `CIVICRM_AUDIT_LOG` | `true` | 启用结构化JSON审计日志记录API调用 |
| `CIVICRM_ALLOWED_TOOLS` | （空） | 以逗号分隔的工具允许列表（空=所有工具） |
## 安全和企业功能
### 审计日志记录
每个CiviCRM API调用都会记录为stdout的结构化JSON，包含时间戳、实体、操作、持续时间和成功/失败状态：
```json
{"timestamp": "2026-05-23T14:30:00Z", "level": "INFO", "logger": "everything_civi.audit", "message": "api4_call", "entity": "Activity", "action": "get", "duration_ms": 42.5, "status": "success", "param_keys": ["select", "where", "limit"]}
```
内置PII保护 - 敏感实体（联系人、电子邮件、电话、地址、贡献、案例等）会对其参数键和错误消息进行日志记录内容的遮蔽。您永远不会在审计输出中看到个人数据。
通过环境变量控制：
```env
CIVICRM_AUDIT_LOG=true # 启用/禁用审计日志记录（默认：true）
CIVICRM_LOG_LEVEL=INFO # 日志级别：DEBUG，INFO，WARNING，ERROR
```
### 工具权限允许列表
限制哪些工具可供MCP客户端访问。设置后，仅列出的工具可用 - 所有其他工具将在启动时被删除：
```env
CIVICRM_ALLOWED_TOOLS=civicrm_get,civicrm_list_entities,civicrm_describe_entity,civicrm_search_contacts
```
当为空或未设置时，默认情况下所有28种工具都可用。资源和提示不会被过滤。
服务器会记录未识别的工具名称的警告和允许列表结果为零的错误。
这是一种纵深防御措施 - CiviCRM还根据经过身份验证的用户角色在其服务器端强制执行其自己的权限模型。
### 每个请求的JWT身份验证转发
客户端支持每个请求的令牌覆盖，用于多用户部署。代替单个静态API密钥，每个API调用都可以携带不同的Bearer令牌：
```python
# 默认：使用配置中的CIVICRM_API_KEY
result = await client.api4("Contact", "get", params)
# 覆盖：对特定调用使用用户JWT
result = await client.api4("Contact", "get", params, token=user_jwt)
```
此功能与CiviCRM的`authx`扩展（从5.36捆绑）一起使用，它通过`Authorization: Bearer`标头接受API密钥和JWT。该令牌永远不会在审计输出中记录。
所有便捷方法（`get`、`create`、`update`、`delete`、`save`、`replace`、`get_fields`、`get_actions`）都接受`token`关键字参数。
### 错误恢复
多步骤工作流工具使用回滚语义防止孤立记录：
- **活动注册付款** (`civicrm_register_for_event`)：如果在创建参与者后贡献或付款链接创建失败，则自动删除参与者。清理失败会在错误消息中报告，以便可以识别孤立记录。
- **带有注释的贡献** (`civicrm_record_contribution`)：如果注释创建失败，则贡献仍会返回警告 - 注释失败不会隐藏成功创建的贡献。
- 所有验证（例如缺少`contribution_amount`）在任何API突变之前运行。
## 架构
```
src/everything_civi/
├── server.py # FastMCP设置、生命周期、工具允许列表
├── config.py # Pydantic设置与环境变量绑定
├── client.py # 异步REST客户端，支持重试、速率限制、审计日志记录
├── logging_config.py # 结构化JSON日志格式化器
├── crud_tools.py # 6种通用CRUD工具
├── discovery_tools.py # 5种模式内省工具
├── workflow_tools.py # 9种特定领域工作流工具
├── searchkit_tools.py # 3种SearchKit工具
├── utility_tools.py # 3种批量操作工具
├── admin_tools.py # 2种管理/健康工具
├── prompts.py # 3种MCP提示
└── resources.py # 3种MCP资源
```
服务器使用分层架构：
1. **核心CRUD** - 通用工具，通过统一的APIv4模式与任何CiviCRM实体一起工作
2. **发现** - 运行时架构内省，以便AI能够学习实体结构
3. **工作流** - 链接API调用，具有名称解析和验证的多步骤操作
4. **SearchKit** - 执行预建的保存搜索
5. **实用工具** - 分页、批量导入和智能联系人匹配
6. **管理** - 健康监控和缓存管理
所有工具通过单个异步REST客户端通信，具备：
- Bearer令牌身份验证（静态API密钥或每个请求的JWT）
- 表单编码的参数传递（CiviCRM REST API要求）
- 暂时错误的重试，指数退避
- 基于信号的速率限制
- 结构化JSON审计日志记录，包含PII遮蔽
- 工具权限允许列表，用于访问控制
- 多步骤操作的回滚语义
- 延迟初始化以避免事件循环问题
## 开发
```bash
# 安装开发依赖项
uv pip install -e ".[dev]"
# 运行测试
.venv/bin/pytest tests/ -v
# 运行集成测试（需要实时CiviCRM）
CIVICRM_BASE_URL=https://your-site.org CIVICRM_API_KEY=your-key \
.venv/bin/pytest tests/test_integration*.py -v
# 校验
.venv/bin/ruff check src/ tests/
```
## 许可证
MIT
