内容
# mcp-server-redcap
一个用于与 [REDCap（研究电子数据采集）](https://projectredcap.org/) 实例交互的 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器。
公开了 38 种工具，涵盖数据访问、项目设计、文件管理和纵向项目结构。设计用于与需要查询或构建 REDCap 项目的 LLM 代理在自然语言对话中使用。
## 工具
### 记录
| 工具 | 描述 |
|------|-------------|
| `导出记录` | 使用可选的字段、记录 ID 或事件筛选器导出记录 |
| `导入记录` | 从 JSON 有效载荷导入记录 |
| `删除记录` | 按 ID 删除记录 |
| `导出报告` | 通过 ID 导出保存的 REDCap 报告 |
| `导出字段名称` | 导出字段名称到导出名称的映射（对于复选框字段必填） |
| `生成下一个记录名称` | 获取项目的自动编号，获取下一个可用的记录 ID |
### 元数据
| 工具 | 描述 |
|------|-------------|
| `获取项目信息` | 检索项目级信息和设置 |
| `获取元数据` | 导出数据字典，可选按字段或表单筛选 |
| `导出日志` | 导出项目审计日志，可按类型、用户、记录或日期范围筛选 |
| `导出重复仪器事件` | 导出重复仪器/事件配置 |
| `导入重复仪器事件` | 更新重复仪器/事件配置 |
### 仪器和项目设计
| 工具 | 描述 |
|------|-------------|
| `获取仪器` | 列出所有具有内部名称和显示标签的仪器 |
| `获取仪器事件映射` | 列出臂/事件/仪器映射（纵向项目） |
| `添加字段` | 向仪器添加新字段（通过数据字典进行往返） |
| `删除字段` | 从数据字典中删除字段 |
| `更新字段` | 更新字段的特定属性，而不影响其他属性 |
| `添加仪器` | 创建新仪器 |
| `删除仪器` | 删除仪器及其所有字段 |
| `重命名仪器` | 重命名仪器的内部名称 |
| `移动字段` | 在数据字典中重新定位字段 |
| `克隆仪器` | 将仪器的所有字段复制到具有字段名称前缀的新仪器中 |
| `将仪器分配给事件` | 将仪器添加到纵向事件 |
| `从事件中解除仪器分配` | 从纵向事件中删除仪器 |
### 分析
| 工具 | 描述 |
|------|-------------|
| `获取项目结构` | 项目的紧凑概述：仪器、字段计数、事件矩阵 |
| `检查字段引用` | 查找在分支逻辑或计算中引用给定字段的所有字段 |
| `验证分支逻辑` | 扫描所有分支逻辑以查找对不存在字段的引用 |
### 文件
| 工具 | 描述 |
|------|-------------|
| `导出文件` | 从记录字段下载文件附件（以 base64 返回） |
| `导入文件` | 将文件上传到记录字段（接受 base64 内容） |
| `删除文件` | 从记录字段删除文件附件 |
| `导出 PDF` | 导出一个或多个仪器的 PDF（以 base64 返回） |
### 臂和事件（纵向）
| 工具 | 描述 |
|------|-------------|
| `导出臂` | 列出臂 |
| `导入臂` | 创建或更新臂 |
| `删除臂` | 按编号删除臂 |
| `导出事件` | 列出事件，可选按臂筛选 |
| `导入事件` | 创建或更新事件 |
| `删除事件` | 按唯一名称删除事件 |
### 调查
| 工具 | 描述 |
|------|-------------|
| `导出调查链接` | 获取记录的参与者特定调查 URL |
| `导出调查参与者列表` | 列出调查参与者及其响应状态 |
## 安装
```bash
pip install mcp-server-redcap
```
或使用 `uv`:
```bash
uvx mcp-server-redcap
```
## REDCap 版本兼容性
服务器适用于运行 **8.0 或更高版本** 的任何 REDCap 实例。大多数工具可从 6.x 版本开始使用，但 `导出 PDF` 需要 8.x 版本。重复仪器（`导出重复仪器事件`、`导入重复仪器事件`）需要 6.16+ 版本。在特定实例上不可用的工具将返回一个纯错误字符串，而不是崩溃。
连接实例的当前 REDCap 版本包含在 `获取项目结构` 的输出中。
## 配置
服务器从环境变量中读取连接详细信息：
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `REDCAP_URL` | 是 | 完整的 REDCap API 端点 URL（例如 `https://redcap.example.org/api/`） |
| `REDCAP_TOKEN` | 是 | REDCap → API → 生成令牌中的项目级 API 令牌 |
| `REDCAP_VERIFY_SSL` | 否 | 设置为 `false` 以跳过 SSL 验证（默认：`true`） |
在工作目录中创建一个 `.env` 文件，服务器将自动加载它：
```env
REDCAP_URL=https://redcap.example.org/api/
REDCAP_TOKEN=您的项目令牌
```
## 与 Claude Code 一起使用
将服务器添加到您的 Claude Code MCP 配置中：
```bash
claude mcp add redcap -e REDCAP_URL=https://redcap.example.org/api/ \
-e REDCAP_TOKEN=您的令牌 -- uvx mcp-server-redcap
```
或手动编辑 `.claude/settings.json`：
```json
{
"mcpServers": {
"redcap": {
"command": "uvx",
"args": ["mcp-server-redcap"],
"env": {
"REDCAP_URL": "https://redcap.example.org/api/",
"REDCAP_TOKEN": "您的项目令牌"
}
}
}
}
```
## 开发
```bash
git clone https://github.com/msicilia/mcp-server-redcap
cd mcp-server-redcap
uv sync --extra dev
```
运行 MCP 检查器进行交互式本地测试：
```bash
uv run mcp dev src/mcp_server_redcap/server.py
```
直接运行服务器（stdio 传输，用于与 MCP 客户端一起使用）：
```bash
uv run mcp-server-redcap
```
## 项目结构
```
src/mcp_server_redcap/
├── __init__.py
├── __main__.py # python -m mcp_server_redcap
├── server.py # FastMCP 服务器工厂和入口点
├── connection.py # REDCap 项目连接（延迟，单例）
└── tools/
├── __init__.py
├── records.py # 记录 CRUD，字段名称，下一个记录名称
├── metadata.py # 项目信息，数据字典，日志记录，重复仪器
├── instruments.py # 仪器列表，字段和仪器突变
├── analysis.py # 项目结构概述，引用和逻辑验证
├── files.py # 文件附件和 PDF 导出
├── arms_events.py # 纵向臂和事件 CRUD
└── surveys.py # 调查链接和参与者列表
```
参见 [DESIGN.md](https://github.com/msicilia/mcp-server-redcap/blob/master/DESIGN.md)，获取完整的 API 参考和设计原理。
## 许可证
MIT
