Zotero MCP Claude Code

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    Zotero Plugin (integrated MCP server)

然后，您的AI助手可以搜索您的库、阅读PDF、提取注释、创建项目、管理收藏等。

快速启动

1.安装插件

下载最新 .xpi 从 发布页面 并通过以下方式将其安装在Zotero中 工具>附加组件.

2.连接克劳德代码

claude mcp add zotero-mcp http://127.0.0.1:23120/mcp -t http

或者添加到您的MCP配置中(~/.claude.json 或 .mcp.json):

{
  "mcpServers": {
    "zotero-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:23120/mcp"
    }
  }
}

如果您已启用 在本地连接上需要身份验证令牌 （或 允许远程访问 --这会强制进行身份验证），从prefs UI复制令牌并将其添加为标头：

{
  "mcpServers": {
    "zotero-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:23120/mcp",
      "headers": {
        "Authorization": "Bearer zmcp_"
      }
    }
  }
}

看 认证 在......下面

3.验证

claude mcp list

你应该看到 zotero-mcp 列出了可用的工具。

支持的客户

插件首选项包括 客户端配置生成器 它为每个客户端生成即用配置。

MCP工具（共36个）

读取工具（21-始终可用）

写入工具（15-在首选项中启用时）

书写工具由以下人员控制 按范围选择加入复选框 在首选项中（请参见 写入范围 在......下面禁用作用域的工具将隐藏起来 tools/list 响应——它们不仅在通话中失败，而且在客户端看到的范围内并不存在。

认证

插件在首次启动时自动生成一个每次安装的承载令牌，存储在 extensions.zotero.zotero-mcp-plugin.mcp.server.authToken 偏好和浮出水面 设置→ Zotero MCP for Claude Code→ MCP服务器→ 认证 和 复制 和 再生 按钮。

当需要身份验证时，通过以下任一方式发送令牌：

Authorization: Bearer zmcp_

或

X-Zotero-MCP-Token: zmcp_

X-Zotero-MCP-Token 存在无法设置的浏览器扩展调用者 Authorization这两个标头都强制CORS预飞行，通过简单的CSRF形式击败了驱动器。

Loopback默认值（无身份验证）使现有的客户端配置保持开箱即用。面向公众或共享的计算机设置应启用 requireAuthThe /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.enabled

从v1.7.0或更早版本升级后首次运行时：

• 如果遗产 mcp.write.enabled 是 true，安全范围(notes, tags, collections, metadata)迁移 上；破坏范围(delete, bulk, import)留下来 关。如果需要，请故意重新启用它们。
• 如果 mcp.write.enabled 未设置或 false，所有作用域默认为关闭。

以编程方式读取作用域状态

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密钥
• 语义索引 --构建/重建/清除索引、自动更新、进度监控

语义搜索

该插件支持使用嵌入向量的人工智能语义搜索：

1. 在首选项中配置嵌入提供程序（OpenAI、Ollama或任何与OpenAI兼容的API）
2. 构建索引（索引项目标题、摘要和全文）
3. 使用 semantic_search 用于自然语言查询或 find_similar 查找相关项目

矢量索引以Int8量化方式本地存储在SQLite中，以实现高效存储。

发展

先决条件

• Zotero 7、8或9
• Node.js 18+

设置

cd zotero-mcp-plugin
npm install
npm run build    # Production build
npm run start    # Dev mode with auto-reload

测试

npm run test:unit    # 37 unit tests (mathUtils, textChunker)
npm run lint:check   # Prettier + ESLint

端点

支持的协议版本： 2024-11-05 和 2025-03-26 （通过协商 initialize).

分叉更改

• 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；放弃了false tools.listChanged 广告
• get_item_details 模式=完成 --现在通过以下方式枚举所有项目类型字段 Zotero.ItemFields.getItemTypeFields，包括 extra （根据Zotero惯例的PMID/PMCID/引用密钥）， collections 会员， dateAdded/dateModified/accessDate对下游标识符提取至关重要。
• 代码库审计 --类型错误、API验证、单例修复、批处理查询、模块重构、37个单元测试

许可证

麻省理工学院

致谢

• 佐特罗 --开源参考资料管理
• 库克约翰/佐特罗mcp --原上游项目
• 模型上下文协议 --协议标准
• Zotero插件模板 --插件脚手架