BibGenieBibGenie

Zotero MCP

配置本地 Zotero MCP 服务器,让 Claude Desktop、Claude Code、Cursor 与 Cherry Studio 检索文献库、读取 PDF 全文并管理笔记。包含详细配置与常见问题解答。

MCP 是 Model Context Protocol。BibGenie 可以启动一个本地 MCP Server,让支持 MCP 的外部客户端访问 Zotero 相关工具。

普通聊天不需要理解 MCP

如果你只在 BibGenie 插件内聊天,不需要手动配置 MCP。MCP 主要面向高级用户、外部客户端和自动化工作流。

MCP 可以做什么?

通过 BibGenie 暴露的 Zotero 工具,外部客户端可以完成这些任务:

  • 搜索 Zotero 条目
  • 基于语义检索文献
  • 读取 PDF 附件
  • 读取网页快照
  • 读取 Zotero 笔记
  • 列出标签和分类
  • 创建 Zotero 笔记
  • 管理标签和分类
  • 获取或编辑元数据

什么是 Zotero MCP?

Zotero MCP 是 BibGenie 在你的 Zotero 文献库和外部 AI 客户端之间建立的本地桥梁。你不需要导出文件,也不需要手动复制元数据,支持 MCP 的外部客户端可以通过本地协议向 BibGenie 请求 Zotero 上下文。

例如,外部客户端可以通过 BibGenie 的 MCP 工具搜索你的文献库、查看分类、读取 PDF 附件,或创建 Zotero 笔记。

核心优势

内置能力

BibGenie 的 MCP Server 运行在 Zotero 插件内部,不需要额外安装 Python 服务或自定义本地后端。

默认本地运行

MCP 服务地址由 Zotero 的本地 HTTP 服务提供,外部客户端在你的设备上和 Zotero 通信。

面向科研工作流

MCP 工具围绕 Zotero 场景设计,涵盖论文、PDF、分类、标签、笔记、网页快照和元数据。

适合外部工作流

MCP 让 Cursor、Claude Code、Claude Desktop、Cherry Studio 等工具可以在自己的界面里使用 Zotero 上下文。

核心功能

功能适合做什么
条目搜索按标题、作者、出版信息、关键词或主题查找论文。
语义检索按语义发现相关论文,而不是只做关键词匹配。
读取元数据在引用、整理或编辑前读取 Zotero 条目的元数据。
阅读 PDF 文本当外部客户端需要论文内容时,读取 Zotero PDF 附件的文本。
查看 PDF 页面图像当页面包含图表、版面或扫描内容时,将 PDF 页面转为图像供视觉检查。
笔记与网页快照读取 Zotero 笔记和网页快照。
文献库整理列出分类和标签,创建分类,管理标签或分类归属。
元数据审查汇总 arXiv、Semantic Scholar、OpenAlex、DBLP、OpenReview 等来源的只读检索结果,提供规范化建议。
写入操作创建笔记、校验并写入元数据等;请在外部客户端中检查操作范围与授权设置。

插件内聊天和 MCP 的区别

使用方式适合用户是否需要配置
BibGenie 插件内聊天大多数用户不需要
本地 MCP Server想把 Zotero 连接到外部 AI 客户端的用户需要在设置中开启

外部客户端的权限与确认机制由该客户端自身控制。不要假设它在向 Zotero 执行写入操作前,会弹出与 BibGenie 插件内相同的确认卡片。在允许外部客户端修改文献库之前,请在客户端中做好相应的权限配置。

虽然 MCP 连接是在本地完成的,但外部客户端在检索到文献内容后,可能会将内容发送给它所连接的模型服务商。在使用私密或未公开的研究材料前,请检查该客户端的模型与数据隐私设置。

Server 类型和 URL

BibGenie 的 MCP Server 使用 Streamable HTTP。Server URL 通常类似:

http://127.0.0.1:23119/bibgenie/mcp

如果你的 Zotero HTTP Server 使用了自定义端口,端口可能不是 23119。请优先复制 BibGenie 设置页中显示的 Server URL,不要手动猜地址。

不要用浏览器直接打开 URL 来判断 MCP 是否可用

MCP 客户端使用 HTTP POST JSON-RPC 请求连接。浏览器地址栏直接打开 Server URL 发出的是 GET 请求,不能可靠判断 MCP 是否可用。请使用 BibGenie 设置里的 Test Connection,或用真正的 MCP 客户端测试。

如何启用 MCP Server

打开 BibGenie 设置页面。

找到 MCP Server 区域。

打开 Enable MCP Server。

复制显示出来的 Server URL。

在外部 MCP 客户端中填写该 URL。

点击 Test Connection 验证连接是否可用。

状态说明

状态含义
Server is offMCP Server 未开启
Starting正在启动
Server running已启动,可供外部客户端连接
Testing connection正在测试连接
Connection verified测试成功
Connection failed测试失败,需要检查 URL 或运行状态

关闭 MCP

不使用外部客户端时,可以关闭 Enable MCP Server。关闭后,外部客户端将无法继续访问 BibGenie 的 MCP 工具。

配置 Zotero MCP

在支持 Streamable HTTP MCP 的客户端中,填写 BibGenie 设置页显示的 Server URL。

客户端配置位置连接方式
Claude Desktopclaude_desktop_config.json通过 npx 启动 mcp-remote,作为本地 stdio 桥接。
Claude Code终端用 claude mcp add 添加 URL,选择 HTTP 传输。
CursorMCP 设置或 mcp.json将 URL 添加为 Streamable HTTP 端点。

验证连接

  1. 保持 Zotero 运行。在 BibGenie 点击 Test Connection,再复制当前服务器地址。
  2. 确认客户端中能看到 list_collections。Claude Code 可以运行 claude mcp list 查看服务器条目。
  3. 让客户端用 list_collections 列出顶层分类,并与 Zotero 里的名称核对。空库返回空列表是正常的。

连接故障排查

现象检查方法
连接被拒绝保持 Zotero 运行,启用 MCP Server,再复制含端口的地址。
404 或 405检查完整路径是否包含 /bibgenie/mcp。使用客户端或 BibGenie 的连接测试。
Claude Desktop 无法启动桥接检查应用能否运行 Node.js 和 npx,确认 JSON 格式正确,保存后重启。
云端连接器无法访问 127.0.0.1在 Zotero 所在电脑上使用客户端的本地配置。
已连接但看不到工具重新连接服务器或重启客户端,刷新工具列表。

Cursor

Cursor 可以直接连接 BibGenie 的 Streamable HTTP endpoint。

打开 Cursor Settings,进入 Tools & MCP。

点击 + New MCP Server。

粘贴以下配置:

{
  "mcpServers": {
    "ZoteroBibGenie": {
      "url": "http://127.0.0.1:23119/bibgenie/mcp"
    }
  }
}

如果 BibGenie 设置页显示的端口不是 23119,请替换为实际 URL。

保存配置。Cursor 显示 MCP server 已连接后,就可以在 Cursor chat 中使用 Zotero 上下文。

Claude Code

Claude Code 可以直接添加 HTTP MCP Server:

claude mcp add ZoteroBibGenie --transport http http://127.0.0.1:23119/bibgenie/mcp

如果 BibGenie 设置页显示的端口不同,请替换为实际 URL。

Claude Desktop

有些 Claude Desktop 版本连接 stdio MCP Server 更稳定。此时可以用 mcp-remote 作为桥接,把 Claude Desktop 连接到 BibGenie 的本地 HTTP Server。

如果系统中不能使用 node 和 npx,先安装 Node.js。

打开 Claude Desktop。

打开 Settings,进入 Developer 区域。

点击 Edit Config,打开 claude_desktop_config.json。

添加以下配置:

{
  "mcpServers": {
    "ZoteroBibGenie": {
      "command": "npx",
      "args": ["mcp-remote", "http://127.0.0.1:23119/bibgenie/mcp"]
    }
  }
}

如果 BibGenie 设置页显示的端口不同,请替换配置里的 URL。

保存文件并重启 Claude Desktop。

Cherry Studio

Cherry Studio 可以直接连接 Streamable HTTP MCP。

打开 Cherry Studio Settings,切换到 MCP 标签。

点击 Add,选择 Quick Create。

填写:

  • Name: ZoteroBibGenie
  • Type: Streamable HTTP
  • URL: 从 BibGenie 设置页复制的 Server URL

Cherry Studio MCP 设置字段

可选:展开 Advanced Settings,填写:

  • Provider URL: https://www.bibgenie.com/
  • Logo URL: https://www.bibgenie.com/favicon.png

Cherry Studio MCP 高级设置

点击 Save,开启该服务,并使用 Cherry Studio 的 verify 按钮测试连接。

示例 Prompt

  • “帮我找 Zotero 中 2023 年之后关于 RAG 的论文。”
  • “读取这个 Zotero 条目的 PDF 附件,并总结论文核心贡献。”
  • “列出 Machine Learning 分类里的文献,并检查哪些条目缺少年份元数据。”

安全建议

  • 只把 MCP Server URL 提供给可信客户端。
  • 涉及写入 Zotero 文献库的工具,例如创建笔记、编辑元数据、管理标签或分类,应谨慎授权。
  • 不使用 MCP 时可以关闭 Server。
  • 如果外部客户端行为异常,先停止 MCP Server,再检查客户端配置。

常见问题