Zotero MCP for Claude Code
一个Zotero插件,通过 模型上下文协议 (MCP)。此分叉增加了Claude Code兼容性和写入操作。
> 注: 这款叉子是用 克劳德代码 上 适用于macOS的Zotero 7–9 (最新macOS)。插件清单声明与Zotero 7、8和9兼容。它使用标准的MCP over Streamable HTTP,因此它应该适用于任何兼容MCP的客户端和平台,但其他客户端和操作系统尚未经过该分支作者的测试。
它做什么
该插件在Zotero内部运行一个MCP服务器,AI客户端通过HTTP连接到该服务器。不需要单独的服务器进程。```
AI Client <--Streamable HTTP--> Zotero Plugin (integrated MCP server)
然后,您的AI助手可以搜索您的库、阅读PDF、提取注释、创建项目、管理收藏等。
## 快速启动
### 1.安装插件
下载最新 `.xpi` 从 发布页面 并通过以下方式将其安装在Zotero中 **工具>附加组件**.
### 2.连接克劳德代码```bash
claude mcp add zotero-mcp http://127.0.0.1:23120/mcp -t http
或者添加到您的MCP配置中(~/.claude.json 或 .mcp.json):```json
{
"mcpServers": {
"zotero-mcp": {
"type": "http",
"url": "http://127.0.0.1:23120/mcp"
}
}
}
如果您已启用 **在本地连接上需要身份验证令牌** (或 **允许远程访问** --这会强制进行身份验证),从prefs UI复制令牌并将其添加为标头:```json
{
"mcpServers": {
"zotero-mcp": {
"type": "http",
"url": "http://127.0.0.1:23120/mcp",
"headers": {
"Authorization": "Bearer zmcp_"
}
}
}
}
看 认证 在......下面
3.验证```bash
claude mcp list
你应该看到 `zotero-mcp` 列出了可用的工具。
## 支持的客户
|客户端|连接|已测试|
|--------|-----------|--------|
| **克劳德代码** |本机HTTP MCP(推荐)|是|
| **克劳德桌面版** |通过mcp-remote可流式传输HTTP |否|
| **光标IDE** |通过mcp-remote可流式传输HTTP |否|
| **樱桃工作室** |本机流式HTTP |否|
| **Gemini CLI** |本机HTTP MCP |否|
| **Cline(VS代码)** |通过mcp-remote可流式传输HTTP |否|
| **Continue.dev** |通过mcp-remote可流式传输HTTP |否|
| **Qwen代码** |本机HTTP MCP |否|
| **聊天框** |通过mcp-remote可流式传输HTTP |否|
| **带来AI** |通过mcp-remote可流式传输HTTP |否|
插件首选项包括 **客户端配置生成器** 它为每个客户端生成即用配置。
## MCP工具(共36个)
### 读取工具(21-始终可用)
|工具|说明|
|------|-------------|
| `search_library` |使用高级过滤(标题、创建者、年份、标签、项目类型、布尔运算符、相关性评分、分页)进行搜索|
| `search_annotations` |按查询、颜色或标签搜索注释/突出显示|
| `get_item_details` |获取项目的完整元数据|
| `get_item_abstract` |获取项目摘要|
| `get_annotations` |获取特定项目的注释|
| `get_content` |从PDF、笔记和附件中提取内容|
| `get_collections` |列出所有收藏|
| `search_collections` |按名称搜索集合|
| `get_collection_details` |获取集合元数据|
| `get_collection_items` |列出集合中的项目|
| `get_subcollections` |列出子收藏|
| `search_fulltext` |在带有上下文片段的附件中进行全文搜索|
| `get_tags` |列出所有带有可选筛选的标签|
| `get_related_items` |通过Zotero的相关功能获取链接|
| `generate_bibliography` |使用Zotero的引文引擎生成格式化引文|
| `search_by_identifier` |按DOI、ISBN或PMID查找库项|
| `get_library_stats` |库摘要:按类型、标签/收藏/垃圾计数的项目计数|
| `get_item_types` |列出所有具有本地化名称的有效Zotero项目类型|
| `get_creator_types` |列出有效的创建者类型,可选择按项目类型筛选|
| `get_item_type_fields` |列出给定项目类型的有效字段|
| `get_trash_items` |按页码列出垃圾箱中的项目|
| `get_recently_modified` |在N天内修改项目|
| `semantic_search` |基于嵌入向量的人工智能语义搜索|
| `find_similar` |查找与给定项目相似的项目|
| `semantic_status` |检查语义索引状态|
| `fulltext_database` |查询全文内容缓存(列表、搜索、获取、统计)|
### 写入工具(15-在首选项中启用时)
|工具|说明|
|------|-------------|
| `create_item` |使用字段、创建者、标签、集合创建新的库项|
| `update_item` |更新现有项目的字段和创建者|
| `add_note` |创建独立笔记或子笔记|
| `update_note` |更新现有笔记的内容和标签|
| `trash_item` |将物品移至回收站|
| `add_tags` |为项目添加标签|
| `remove_tags` |从项目中删除标签|
| `rename_tag` |重命名库中所有项目的标记|
| `delete_tag` |从整个库中删除标记|
| `create_collection` |创建新集合或子集合|
| `rename_collection` |重命名集合|
| `delete_collection` |删除收藏(可选择删除的项目)|
| `move_collection` |将集合移动到新的父级或根级|
| `add_to_collection` |将项目添加到集合|
| `remove_from_collection` |从集合中删除项目|
| `move_item_to_collection` |在集合之间原子移动项目|
| `add_related_item` |在项目之间创建双向相关链接|
| `remove_related_item` |删除项目之间的相关链接|
| `import_attachment_url` |从URL导入文件作为附件|
| `batch_tag` |一次标记多个项目(最多100个)|
| `batch_add_to_collection` |将多个项目添加到集合中(最多100个)|
| `batch_remove_from_collection` |从集合中删除多个项目(最多100个)|
| `batch_trash` |一次回收多个物品(最多100个)|
| `restore_from_trash` |将被丢弃的项目还原回库|
书写工具由以下人员控制 **按范围选择加入复选框** 在首选项中(请参见 写入范围 在......下面禁用作用域的工具将隐藏起来 `tools/list` 响应——它们不仅在通话中失败,而且在客户端看到的范围内并不存在。
## 认证
插件在首次启动时自动生成一个每次安装的承载令牌,存储在 `extensions.zotero.zotero-mcp-plugin.mcp.server.authToken` 偏好和浮出水面 **设置→ Zotero MCP for Claude Code→ MCP服务器→ 认证** 和 **复制** 和 **再生** 按钮。
|前置|默认|行为|
|---|---|---|
| `mcp.server.allowRemote` | `false` |何时 `true`,监听器绑定 `0.0.0.0` 和 **身份验证是必需的** 不管 `requireAuth` |
| `mcp.server.requireAuth` | `false` |何时 `true`,环回调用者还必须提供令牌|
当需要身份验证时,通过以下任一方式发送令牌:```http
Authorization: Bearer zmcp_<48-hex-chars>
或```http
X-Zotero-MCP-Token: zmcp_<48-hex-chars>
`X-Zotero-MCP-Token` 存在无法设置的浏览器扩展调用者 `Authorization`这两个标头都强制CORS预飞行,通过简单的CSRF形式击败了驱动器。
Loopback默认值(无身份验证)使现有的客户端配置保持开箱即用。面向公众或共享的计算机设置应启用 `requireAuth`The `/ping`, `/capabilities`, `/help`, `/mcp/status`,以及 `GET /mcp` 即使启用了auth,端点也会保持打开状态,因此健康检查和配置生成器不需要凭据。
**正在重新生成令牌** 使每个现有的客户端配置无效——客户端将获得401,直到您更新它们。
### 纵深防御检查(始终开启)
无论身份验证状态如何,这些都会运行:
- `Origin: null` (沙盒iframe, `file://`,跨源重定向)被拒绝
- `POST /mcp` 需要 `Content-Type: application/json` (失败 `text/plain` CSRF通过简单的POST形式)
- `Host` 当发生以下情况时,标头必须是环回的 `allowRemote=false`
- 重复 `Host` 标头被拒绝
- `Mcp-Session-Id` 经过验证 `^mcp-[a-f0-9-]{8,80}$` 限制在256个活跃会话,LRU被驱逐
- 全局+每IP+每会话令牌桶速率限制,写入工具上的桶更严格
- 完整请求正文阅读后10秒挂钟截止日期
- `Content-Length > 1MB` 阅读前被拒绝
## 写入范围
`mcp.write.enabled` (单个布尔值)在v1.8.0中被替换为 **七粒度镜**工具仅在以下情况下暴露 `tools/list` 当 **它所要求的每一个范围** 已启用。
|作用域预选项|工具|
|---|---|
| `mcp.write.notes` | `add_note`, `update_note` |
| `mcp.write.tags` | `add_tags`, `remove_tags` |
| `mcp.write.collections` | `add_to_collection`, `remove_from_collection`, `create_collection`, `rename_collection`, `move_collection`, `move_item_to_collection` |
| `mcp.write.metadata` | `create_item`, `update_item`, `add_related_item`, `remove_related_item` |
| `mcp.write.delete` ⚠ | `trash_item`, `restore_from_trash`, `delete_collection` |
| `mcp.write.bulk` ⚠ | (结合批量操作的另一个范围——见下文)|
| `mcp.write.import` ⚠ | `import_attachment_url` (SSRF风险)|
标记的范围⚠ 具有破坏性,默认为关闭。多范围工具需要 **全部** 列出的范围:
|工具|需要范围|
|---|---|
| `batch_tag` | `bulk` + `tags` |
| `batch_add_to_collection` | `bulk` + `collections` |
| `batch_remove_from_collection` | `bulk` + `collections` |
| `batch_trash` | `bulk` + `delete` |
| `delete_tag` | `delete` + `bulk` (整个图书馆)|
| `rename_tag` | `tags` + `bulk` (全库重写)|
| `delete_collection` 和 `deleteItems: true` | `delete` + `bulk` |
### 迁移自 `mcp.write.enabled`
从v1.7.0或更早版本升级后首次运行时:
- 如果遗产 `mcp.write.enabled` 是 `true`,安全范围(`notes`, `tags`, `collections`, `metadata`)迁移 **上**;破坏范围(`delete`, `bulk`, `import`)留下来 **关**。如果需要,请故意重新启用它们。
- 如果 `mcp.write.enabled` 未设置或 `false`,所有作用域默认为关闭。
### 以编程方式读取作用域状态```js
Zotero.Prefs.get("extensions.zotero.zotero-mcp-plugin.mcp.write.metadata", true)
// → true | false | undefined
相同的pref键出现在 ~/Library/Application Support/Zotero/Profiles//prefs.js.
插件首选项
在中配置 Zotero>设置>用于克劳德代码的Zotero MCP:
- MCP服务器 --启用/禁用、端口(默认23120)、远程访问
- 认证 --承载令牌(复制/重新生成),在环回切换时需要身份验证
- 写入作用域 --按范围选择加入(注释、标签、集合、元数据、删除、批量、导入)
- 客户端配置生成器 --为任何受支持的AI客户端生成配置JSON
- MCP内容设置 --内容处理模式(最小/预览/标准/完整/自定义),最大令牌
- 语义搜索 --嵌入提供商(OpenAI、Ollama等)、模型、尺寸、API密钥
- 语义索引 --构建/重建/清除索引、自动更新、进度监控
语义搜索
该插件支持使用嵌入向量的人工智能语义搜索:
- 在首选项中配置嵌入提供程序(OpenAI、Ollama或任何与OpenAI兼容的API)
- 构建索引(索引项目标题、摘要和全文)
- 使用
semantic_search用于自然语言查询或find_similar查找相关项目
矢量索引以Int8量化方式本地存储在SQLite中,以实现高效存储。
发展
先决条件
- Zotero 7、8或9
- Node.js 18+
设置```bash
cd zotero-mcp-plugin
npm install
npm run build # Production build
npm run start # Dev mode with auto-reload
### 测试```bash
npm run test:unit # 37 unit tests (mathUtils, textChunker)
npm run lint:check # Prettier + ESLint
端点
| 端点 | 方法 | 目的 | 在以下情况下需要授权 requireAuth=true |
|---|---|---|---|
/mcp |
POST | MCP JSON-RPC 2.0请求 | 是 |
/mcp |
GET | 端点信息(JSON) | 否 |
/mcp |
删除 | 会话终止(根据MCP 2025-03-26规范) | 否 |
/ping |
GET | 健康检查(返回 pong) |
没有 |
/mcp/status |
GET | 服务器状态 | 否 |
/capabilities |
GET | 服务器功能(也在 /help, /mcp/capabilities) |
没有 |
支持的协议版本:
2024-11-05 和 2025-03-26 (通过协商 initialize).
分叉更改
这个叉子(lricher7329/zotero mcp-claude代码)在上游之上添加以下内容 库克约翰/佐特罗mcp:
- Claude代码兼容性 --正确的请求体读取、Accept标头验证、DELETE方法、通知处理、批处理请求、双协议版本支持(
2024-11-05+2025-03-26) - 写入操作 --约24个MCP编写工具,用于创建/更新项目、注释、标签、集合、关系和附件,以及批处理操作和垃圾管理——所有这些都由每个范围的选择入口控制
- 图书馆反思 --模式发现工具(项目类型、创建者类型、字段列表)、库统计信息、垃圾列表、最近修改的项目
- 安全强化(v1.8.0) --每次安装承载令牌认证;来源/内容类型CSRF保护;按作用域写入选项(破坏性操作默认关闭);全局+每IP+每会话速率限制;具有IPv6-mapped-IPv4和十进制/八进制IPv4检测的SSRF防护;itemKey/collectionKey格式验证;使用LRU帽进行会话ID硬化;正文阅读截止日期;已清理的错误消息
- MCP/JSON-RPC合规性修复(v1.8.0) --工具执行失败返回为
result.isError(LLM可以恢复)而不是-32603;参数验证映射到-32602;解析错误id: null符合规范;notifications/initialized对的;空批次退货-32600;放弃了falsetools.listChanged广告 get_item_details模式=完成 --现在通过以下方式枚举所有项目类型字段Zotero.ItemFields.getItemTypeFields,包括extra(根据Zotero惯例的PMID/PMCID/引用密钥),collections会员,dateAdded/dateModified/accessDate对下游标识符提取至关重要。- 代码库审计 --类型错误、API验证、单例修复、批处理查询、模块重构、37个单元测试
许可证
麻省理工学院
致谢
- 佐特罗 --开源参考资料管理
- 库克约翰/佐特罗mcp --原上游项目
- 模型上下文协议 --协议标准
- Zotero插件模板 --插件脚手架
