Zotero Write MCP

佐特罗写mcp

](https://www.python.org/downloads/)  

用于编写、编辑和合并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：使用紫外线（推荐）

# 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

# 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：来源

git clone https://github.com/rcesaret/zotero-write-mcp.git
cd zotero-write-mcp
pip install -e .

验证安装

zotero-write-mcp --version
# Or test the server starts correctly:
zotero-write-mcp
# Press Ctrl+C to exit

⚙️ 配置

环境变量

MCP客户端配置

帆板运动

添加 ~/.codeium/windsurf/mcp_config.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

{
  "mcpServers": {
    "zotero-write": {
      "command": "zotero-write-mcp",
      "env": {
        "ZOTERO_API_KEY": "your-api-key-here",
        "SAFETY_MODE": "standard"
      }
    }
  }
}

Cline（VS代码扩展）

添加到Cline的MCP设置中：

{
  "mcpServers": {
    "zotero-write": {
      "command": "zotero-write-mcp",
      "env": {
        "ZOTERO_API_KEY": "your-api-key-here",
        "SAFETY_MODE": "standard"
      }
    }
  }
}

其他MCP客户端

任何兼容MCP的客户端都可以使用此服务器。服务器使用stdio传输并遵循 MCP规范.

🚦 快速开始

1. 获取Zotero API密钥

- 访问https://www.zotero.org/settings/keys - 点击“创建新私钥” - 为其命名（例如，“MCP服务器”） - 启用“允许库访问” 读写权限 权限 - 复制生成的密钥

1. 确保Zotero正在运行

- 启动Zotero 7+桌面应用程序 - 本地API在上自动运行 http://127.0.0.1:23119

1. 配置您的MCP客户端

- 将服务器添加到MCP客户端的配置中（见上面的示例） - 设置您的 ZOTERO_API_KEY 在环境变量中

1. 测试连接

- 问你的人工智能助手：“列出Zotero可用的工具” - 尝试创建一个测试项目：“在我的Zotero库中创建一篇测试日志文章”

1. 探索工具

- 看 工具概述 下节 - 检查 API_REFERENCE.md 详细的参数文档

🔧 工具概述（18）

所有工具都完整记录在 API_REFERENCE.md 包括参数细节和示例。

创作（3）

从各种来源创建新的Zotero物品。

编辑（5）

修改现有项目及其元数据。

合并与审计（5）

查找重复项、比较项目并执行库审核。

文件操作（5）

管理附件和批量链接文件到库项目。

🛡️ 安全模式

配置服务器如何处理潜在的破坏性操作：

破坏性行动: merge_items （删除次要项目）， bulk_link_files （批量写入）

通过设置 SAFETY_MODE 环境变量或提示您的AI助手在会话期间“切换到严格安全模式”。

💡 使用示例

从DOI创建项目

You: Add the paper with DOI 10.1038/nature12373 to my library

服务器将：

1. 从Crossref获取元数据
2. 检查重复项
3. 如果不存在重复项，则创建该项
4. 返回新项目密钥

批量链接PDF

You: Scan ~/Papers/2024 for PDFs and link them to matching items in my library

服务器将：

1. 从PDF中提取元数据（标题、作者、DOI（如果存在））
2. 在库中查找匹配的项目
3. 出示比赛以供确认（in standard 模式）
4. 将文件链接到已确认的匹配项

查找和合并重复项

You: Find duplicate items in my library and help me merge them

服务器将：

1. 扫描库以查找潜在的重复项
2. 显示并排比较
3. 让您选择要保留哪些字段
4. 确认后合并项目

批量验证

You: Check all my conference papers for missing fields

服务器将：

1. 按类型筛选项目（conferencePaper）
2. 检查常见的缺失字段（地点、日期、页面）
3. 使用项目键报告问题，以便于修复

🤝 配套服务器

此服务器处理 写.为 读取/搜索，使用伴侣 zotero-mcp 服务器提供20个只读工具，包括：

• 🔍 跨库的语义搜索
• 📄 从PDF中检索全文
• 📝 注释访问和过滤
• 📚 收藏浏览和管理
• 🔗 引文网络探索

总共：38个Zotero工具 可用于任何MCP客户端——为您的研究库完成CRUD操作。

📐 技术规格

依赖项

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中

# 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编码

# 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\

🤝 贡献

欢迎投稿！该项目正在准备公开发布。

开发设置

# 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框架

📄 许可证

麻省理工学院