佐特罗写mcp
用于编写、编辑和合并Zotero库条目的模型上下文协议(MCP)服务器。 设计为 写补语 到只读 zotero-mcp 服务器——它们共同为AI代理(Claude、Windsurf、Cline等)提供了对Zotero库的完全CRUD访问权限。
✨ 主要特点
- 18个强大的工具 --完成Zotero项目、标签、附件和元数据的CRUD操作
- 混合API体系结构 --快速的本地读取,可靠的云写入
- 智能重复检测 --模糊匹配和合并功能
- DOI和BibTeX支持 --从DOI或BibTeX字符串创建条目
- 批量文件操作 --扫描目录、提取元数据、批量附加PDF
- 可配置的安全模式 --严格、标准或自主操作
- 零配置本地设置 -适用于Zotero 7+本地API(无需额外设置)
📋 目录
- 主要特点
- 建筑
- 需求
- 安装
- 配置
- 快速开始
- 工具概述
- 安全模式
- 使用示例
- 配套服务器
- 技术规格
- 故障排除
- 贡献
- 许可证
🏗 建筑
混合API客户端 -通过Zotero本地API读取(http://127.0.0.1:23119),通过Zotero Web API编写(https://api.zotero.org).这避免了本地API的只读限制,同时保持读取速度快且可脱机。```
┌──────────────┐ local API (reads) ┌─────────────┐
│ MCP Client │◄──────────────────────────► │ Zotero 7+ │
│ (Windsurf, │ web API (writes) │ Desktop │
│ Claude) │◄──────────────────────────► │ + Cloud │
└──────────────┘ └─────────────┘
### 为什么是混合动力?
- **快速阅读**:本地API立即响应,离线工作
- **可靠的写作**:Web API确保设备之间的数据一致性
- **无同步延迟**:更改通过Zotero的同步系统传播
- **全功能访问**:Web API支持所有写入操作
## 📦 需求
- **python** ≥ 3.10
- **佐特罗7+** 在启用本地API的情况下运行(在Zotero 7+中自动启用)
- **Zotero Web API密钥** --生成时间https://www.zotero.org/settings/keys
- 所需权限: **读写** 访问您的图书馆
- 将从API密钥自动检测用户ID
- **紫外线** 包管理器(推荐)或pip
## 🚀 安装
### 方法1:使用紫外线(推荐)```bash
# Install from local directory
uv tool install /path/to/zotero-write-mcp --force
# Or install from GitHub
uv tool install git+https://github.com/rcesaret/zotero-write-mcp.git
可执行文件安装到:
- Unix/macOS:
~/.local/bin/zotero-write-mcp - 视窗:
%USERPROFILE%\.local\bin\zotero-write-mcp.exe
方法2:使用pip```bash
Install from local directory
pip install /path/to/zotero-write-mcp
Or install from GitHub
pip install git+https://github.com/rcesaret/zotero-write-mcp.git
### 方法3:来源```bash
git clone https://github.com/rcesaret/zotero-write-mcp.git
cd zotero-write-mcp
pip install -e .
验证安装```bash
zotero-write-mcp --version
Or test the server starts correctly:
zotero-write-mcp
Press Ctrl+C to exit
## ⚙️ 配置
### 环境变量
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `ZOTERO_API_KEY` | **是** |-| Zotero Web API密钥(生成于https://www.zotero.org/settings/keys) |
| `SAFETY_MODE` |没有| `standard` |安全等级: `strict`, `standard`,或 `autonomous` |
| `ZOTERO_LOCAL_URL` |没有| `http://127.0.0.1:23119/api` |Zotero本地API基础URL|
### MCP客户端配置
#### 帆板运动
添加 `~/.codeium/windsurf/mcp_config.json`:```json
{
"mcpServers": {
"zotero-write": {
"command": "zotero-write-mcp",
"env": {
"ZOTERO_API_KEY": "your-api-key-here",
"SAFETY_MODE": "standard"
}
}
}
}
windows用户:使用完整路径,如 "C:\\Users\\\\.local\\bin\\zotero-write-mcp.exe"
> ⚠️ BOM警告:永远不要使用PowerShell Set-Content -Encoding UTF8 上 mcp_config.json --它注入了一个破坏Windsurf JSON解析器的BOM。使用 [System.IO.File]::WriteAllText() 随着 UTF8Encoding($false) 相反。
克劳德桌面版
添加到:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: `%APPDATA%\Claude\claude_desktop_config.json````json
{
"mcpServers": {
"zotero-write": {
"command": "zotero-write-mcp",
"env": {
"ZOTERO_API_KEY": "your-api-key-here",
"SAFETY_MODE": "standard"
}
}
}
}
#### Cline(VS代码扩展)
添加到Cline的MCP设置中:```json
{
"mcpServers": {
"zotero-write": {
"command": "zotero-write-mcp",
"env": {
"ZOTERO_API_KEY": "your-api-key-here",
"SAFETY_MODE": "standard"
}
}
}
}
其他MCP客户端
任何兼容MCP的客户端都可以使用此服务器。服务器使用stdio传输并遵循 MCP规范.
🚦 快速开始
- 获取Zotero API密钥
- 访问https://www.zotero.org/settings/keys
- 点击“创建新私钥”
- 为其命名(例如,“MCP服务器”)
- 启用“允许库访问” 读写权限 权限
- 复制生成的密钥
- 确保Zotero正在运行
- 启动Zotero 7+桌面应用程序
- 本地API在上自动运行
http://127.0.0.1:23119
- 配置您的MCP客户端
- 将服务器添加到MCP客户端的配置中(见上面的示例)
- 设置您的
ZOTERO_API_KEY在环境变量中
- 测试连接
- 问你的人工智能助手:“列出Zotero可用的工具”
- 尝试创建一个测试项目:“在我的Zotero库中创建一篇测试日志文章”
- 探索工具
- 看 工具概述 下节
- 检查 API_REFERENCE.md 详细的参数文档
🔧 工具概述(18)
所有工具都完整记录在 API_REFERENCE.md 包括参数细节和示例。
创作(3)
从各种来源创建新的Zotero物品。
| 工具 | 说明 |
|---|---|
create_item |
从显式元数据字段创建项目 |
create_item_from_doi |
通过Crossref解析DOI,创建具有自动数据消除功能的条目 |
create_item_from_bibtex |
将BibTeX字符串解析为Zotero项 |
编辑(5)
修改现有项目及其元数据。
| 工具 | 说明 |
|---|---|
update_item_fields |
更新现有项目上的特定字段 |
add_tags_to_item |
添加标签而不删除现有标签 |
remove_tags_from_item |
删除特定标签 |
validate_item |
检查项目的完整性/格式问题 |
get_item_type_fields |
列出任何Zotero项目类型的有效字段 |
合并与审计(5)
查找重复项、比较项目并执行库审核。
| 工具 | 说明 |
|---|---|
find_duplicate_candidates |
用于重复对的模糊扫描库 |
find_duplicates_for_item |
查找特定项目的重复项 |
compare_items_for_merge |
并排逐场差异 |
merge_items |
使用每个字段控件合并两个项目(预览+确认) |
batch_validate_items |
对缺失字段和格式问题进行审核扫描 |
文件操作(5)
管理附件和批量链接文件到库项目。
| 工具 | 说明 |
|---|---|
attach_file_linked |
将磁盘上的文件链接到Zotero项目(无副本) |
attach_file_imported |
将文件副本上传到Zotero云存储 |
check_item_attachments |
列出项目的所有附件 |
scan_directory_for_sources |
扫描PDF/MD目录,提取元数据,匹配库 |
bulk_link_files |
将文件批量附加到匹配的项目 |
🛡️ 安全模式
配置服务器如何处理潜在的破坏性操作:
| 模式 | 低风险操作 | 破坏性操作 | 用例 |
|---|---|---|---|
strict |
确认 | 确认 | 最大限度的谨慎——确认一切 |
standard |
自动执行 | 需要确认 | 默认 --日常使用,确认破坏性操作 |
autonomous |
自动执行 | 自动执行 | 批处理脚本--无需确认 |
破坏性行动: merge_items (删除次要项目), bulk_link_files (批量写入)
通过设置 SAFETY_MODE 环境变量或提示您的AI助手在会话期间“切换到严格安全模式”。
💡 使用示例
从DOI创建项目```
You: Add the paper with DOI 10.1038/nature12373 to my library
服务器将:
1. 从Crossref获取元数据
1. 检查重复项
1. 如果不存在重复项,则创建该项
1. 返回新项目密钥
### 批量链接PDF```
You: Scan ~/Papers/2024 for PDFs and link them to matching items in my library
服务器将:
- 从PDF中提取元数据(标题、作者、DOI(如果存在))
- 在库中查找匹配的项目
- 出示比赛以供确认(in
standard模式) - 将文件链接到已确认的匹配项
查找和合并重复项```
You: Find duplicate items in my library and help me merge them
服务器将:
1. 扫描库以查找潜在的重复项
1. 显示并排比较
1. 让您选择要保留哪些字段
1. 确认后合并项目
### 批量验证```
You: Check all my conference papers for missing fields
服务器将:
- 按类型筛选项目(conferencePaper)
- 检查常见的缺失字段(地点、日期、页面)
- 使用项目键报告问题,以便于修复
🤝 配套服务器
此服务器处理 写.为 读取/搜索,使用伴侣 zotero-mcp 服务器提供20个只读工具,包括:
- 🔍 跨库的语义搜索
- 📄 从PDF中检索全文
- 📝 注释访问和过滤
- 📚 收藏浏览和管理
- 🔗 引文网络探索
总共:38个Zotero工具 可用于任何MCP客户端——为您的研究库完成CRUD操作。
📐 技术规格
依赖项
| 包装 | 版本 | 用途 |
|---|---|---|
fastmcp |
≥2.0 | MCP服务器框架 |
httpx |
≥0.27 | 用于API调用的异步HTTP客户端 |
bibtexparser |
≥1.4,\<2.0 | BibTeX解析和转换 |
API终点
- 当地API:
http://127.0.0.1:23119/api(读取操作) - Web API:
https://api.zotero.org/(写入操作)
速率限制
服务器遵守Zotero Web API速率限制:
- 用户库:120个请求/分钟
- 组库:120个请求/分钟
- 对429个响应自动重试并回退
数据流```
MCP Request → Tool Handler → Safety Check → API Client
├─► Local API (read)
└─► Web API (write)
Response ← Format Result ← Parse Response ← API Client
### 文件结构```
zotero-write-mcp/
├── pyproject.toml # Package configuration
├── README.md # This file
├── API_REFERENCE.md # Detailed tool documentation
└── src/
└── zotero_write_mcp/
├── __init__.py # Package initialization
├── __main__.py # Entry point (FastMCP stdio transport)
├── server.py # FastMCP server + 18 tool definitions
├── client.py # Hybrid API client (local reads, web writes)
├── fileops.py # File scanning, PDF metadata extraction
├── safety.py # Safety mode logic and confirmation handling
└── utils.py # DOI resolution, BibTeX parsing, fuzzy matching
支持的项目类型
支持所有Zotero项目类型:
- 文章:
journalArticle,magazineArticle,newspaperArticle - 书:
book,bookSection - 学术:
thesis,conferencePaper,report - 媒体:
film,tvBroadcast,podcast,videoRecording,audioRecording - 法律:
case,statute,patent - 网状物:
webpage,blogPost,forumPost - 还有更多——看
get_item_type_fields工具
🐛 故障排除
服务器无法启动
问题: zotero-write-mcp 命令未找到\
解决方案:确保安装目录在PATH中```bash
Unix/macOS
export PATH="$HOME/.local/bin:$PATH"
Windows (PowerShell)
$env:PATH = "$env:USERPROFILE.local\bin;$env:PATH"
### API关键问题
**问题**:“无效的API密钥”或“身份验证失败”\
**解决方案**:
- 在验证您的API密钥https://www.zotero.org/settings/keys
- 确保它有 **读写权限** 权限
- 检查一下 `ZOTERO_API_KEY` 在MCP客户端配置中设置正确
- JSON配置中不需要引号--使用 `"ZOTERO_API_KEY": "abcd1234"`
### 本地API连接失败
**问题**:“无法连接到本地API”\
**解决方案**:
- 确保Zotero 7+桌面应用程序正在运行
- 检查本地API是否已启用(Zotero 7+中默认为启用)
- 验证端口23119中没有其他使用
- 尝试访问 `http://127.0.0.1:23119/api` 在浏览器中
### 速率限制
**问题**:“请求太多”或429个错误\
**解决方案**:
- 服务器自动重试并回退
- 减少批量操作规模
- 请等待一分钟,然后重试失败的操作
### JSON配置中的BOM问题(Windows)
**问题**:MCP客户端无法解析配置文件\
**解决方案**:不要使用PowerShell `Set-Content` 采用UTF8编码```powershell
# Wrong (adds BOM):
Get-Content config.json | Set-Content -Encoding UTF8 config.json
# Right (no BOM):
$json = Get-Content config.json -Raw
[System.IO.File]::WriteAllText("config.json", $json, [System.Text.UTF8Encoding]::new($false))
调试
在MCP客户端中启用详细日志记录,以查看详细的错误消息:
帆板运动:检查MCP服务器日志的输出面板\
克劳德桌面版:查看日志:
- macOS:
~/Library/Logs/Claude/ - 窗户:
%APPDATA%\Claude\logs\
🤝 贡献
欢迎投稿!该项目正在准备公开发布。
开发设置```bash
Clone the repository
git clone https://github.com/rcesaret/zotero-write-mcp.git
cd zotero-write-mcp
Install in development mode
pip install -e .
Test the server
zotero-write-mcp
```
指南
- 遵循现有代码样式
- 为新功能添加测试
- 为新工具更新API_REFERENCE.md
- 保持README最新
报告问题
请在以下网址报告问题:https://github.com/rcesaret/zotero-write-mcp/issues
包括:
- 你的Python版本(
python --version) - 您的Zotero版本
- 您正在使用的MCP客户端(Windsurf、Claude等)
- 错误消息或意外行为
- 重现步骤
📚 其他资源
- API 参考 --所有18个工具的详细文档
- MCP规范 --了解模型上下文协议
- Zotero Web API文档 -Zotero API参考
- FastMCP框架 --基础MCP框架
📄 许可证
麻省理工学院
