Zotero MCP：在Claude、ChatGPT和其他平台中与您的研究库进行对话——本地或在线。

<p align="center"> <a href="https://www.zotero.org/"> <img src="https://img.shields.io/badge/Zotero-CC2936?style=for-the-badge&logo=zotero&logoColor=white" alt="Zotero"> </a> <a href="https://www.anthropic.com/claude"> <img src="https://img.shields.io/badge/Claude-6849C3?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude"> </a> <a href="https://chatgpt.com/"> <img src="https://img.shields.io/badge/ChatGPT-74AA9C?style=for-the-badge&logo=openai&logoColor=white" alt="ChatGPT"> </a> <a href="https://modelcontextprotocol.io/introduction"> <img src="https://img.shields.io/badge/MCP-0175C2?style=for-the-badge&logoColor=white" alt="MCP"> </a> </p>

Zotero MCP通过模型上下文协议，无缝连接您的Zotero研究库与ChatGPT、Claude以及其他AI助手（例如Cherry Studio、Chorus、Cursor）。审查论文、获取摘要、分析引用、提取PDF注释等！

✨ 特性

🧠 AI驱动的语义搜索

• 基于向量的相似度搜索覆盖整个研究库
• 多种嵌入模型：默认（免费）、OpenAI 和 Gemini 选项
• 智能结果带有相似度评分和上下文匹配
• 自动更新数据库可配置同步计划

🔍 搜索您的库

• 根据标题、作者或内容查找论文、文章和书籍
• 使用多个标准执行复杂搜索
• 浏览集合、标签和最近添加的内容
• 新功能：概念和主题导向的语义搜索

📚 访问您的内容

• 获取任何项目的详细元数据
• 获取全文内容（当可用时）
• 访问附件、笔记和子项目

📝 处理注释

• 直接提取和搜索PDF注释
• 访问Zotero的原生注释
• 创建和更新笔记和注释

🔄 简单更新

• 智能更新系统检测安装方法（uv、pip、conda、pipx）
• 配置保留 - 更新期间所有设置均被保留
• 版本检查和自动更新通知

🌐 灵活访问方式

• 本地方法用于离线访问（无需API密钥）
• Web API用于云库访问
• 适用于本地研究和远程协作

🚀 快速安装

默认安装

通过uv安装

uv tool install "git+https://github.com/54yyyu/zotero-mcp.git"
zotero-mcp setup  # 自动配置（支持Claude Desktop）

通过pip安装

pip install git+https://github.com/54yyyu/zotero-mcp.git
zotero-mcp setup  # 自动配置（支持Claude Desktop）

通过Smithery安装

要通过Smithery安装Zotero MCP以供Claude Desktop使用：

npx -y @smithery/cli install @54yyyu/zotero-mcp --client claude

更新您的安装

使用智能更新命令保持zotero-mcp最新：

# 检查更新
zotero-mcp update --check-only

# 更新到最新版本（保留所有配置）
zotero-mcp update

🧠 语义搜索

Zotero MCP现在包括强大的AI驱动的语义搜索能力，让您能够根据概念和意义找到研究，而不仅仅是关键词。

设置语义搜索

在设置过程中或单独配置语义搜索：

# 在初始设置期间配置（推荐）
zotero-mcp setup

# 或单独配置语义搜索
zotero-mcp setup --semantic-config-only

可用嵌入模型：

• 默认（all-MiniLM-L6-v2）：免费，本地运行，适合大多数用例
• OpenAI：质量更好，需要API密钥（text-embedding-3-small或text-embedding-3-large）
• Gemini：质量更好，需要API密钥（models/text-embedding-004或实验模型）

更新频率选项：

• 手动：仅在您运行zotero-mcp update-db时更新
• 启动时自动：每次服务器启动时更新数据库
• 每日：每天自动更新一次
• 每N天：设置自定义间隔

使用语义搜索

设置后，初始化您的搜索数据库：

# 构建语义搜索数据库（快速，仅元数据）
zotero-mcp update-db

# 构建并提取全文（较慢，更全面）
zotero-mcp update-db --fulltext

# 检查数据库状态
zotero-mcp db-status

示例语义查询在您的AI助手中：

• "找到与神经科学中的机器学习概念相似的研究"
• "讨论农业气候变化影响的论文"
• "与量子计算应用相关的研究"
• "关于社交媒体对心理健康影响的研究"
• "找到概念上与此摘要相似的论文：[粘贴摘要]"

语义搜索提供相似度评分，并基于概念理解找到论文，而不仅仅是关键词匹配。

🖥️ 设置与使用

完整的文档可在Zotero MCP文档中找到。

需求

• Python 3.10+
• Zotero 7+（对于具有全文访问权限的本地API）
• 兼容MCP的客户端（例如，Claude Desktop、ChatGPT开发者模式、Cherry Studio、Chorus）

对于ChatGPT设置，请参阅入门指南。

对于Claude Desktop（示例MCP客户端）

配置

安装后，可以：

1. 自动配置（推荐）：

   zotero-mcp setup
   

2. 手动配置： 添加到您的claude_desktop_config.json：

   {
     "mcpServers": {
       "zotero": {
         "command": "zotero-mcp",
         "env": {
           "ZOTERO_LOCAL": "true"
         }
       }
     }
   }
   

使用

1. 启动Zotero桌面（确保偏好设置中启用了本地API）
2. 启动Claude Desktop
3. 通过Claude Desktop的工具界面访问Zotero-MCP工具

示例提示：

• "在我的图书馆中搜索有关机器学习的论文"
• "找到我最近添加的关于气候变化的文章"
• "总结我关于量子计算的论文的关键发现"
• "从我的关于神经网络的论文中提取所有PDF注释"
• "在我的笔记和注释中搜索提到‘强化学习’的内容"
• "显示标记为'#Arm'且不包含'#Crypt'的论文"
• "搜索带有'#Arm'标签的操作系统论文"
• "导出关于机器学习论文的BibTeX引用"
• "找到与计算机视觉中的深度学习概念相似的论文" (语义搜索)
• "与人工智能和医疗保健交叉领域的研究" (语义搜索)
• "讨论与这个摘要相似的主题的论文：[粘贴文本]" (语义搜索)

对于Cherry Studio

配置

转到设置 -> MCP服务器 -> 编辑MCP配置，并添加以下内容：

{
  "mcpServers": {
    "zotero": {
      "name": "zotero",
      "type": "stdio",
      "isActive": true,
      "command": "zotero-mcp",
      "args": [],
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}

然后点击“保存”。

Cherry Studio还提供了通用设置和工具选择的可视化配置方法。

🔧 高级配置

使用Web API而不是本地API

为了通过Web API访问您的Zotero库（适用于远程设置）：

zotero-mcp setup --no-local --api-key YOUR_API_KEY --library-id YOUR_LIBRARY_ID

环境变量

Zotero连接：

• ZOTERO_LOCAL=true：使用本地Zotero API（默认：false）
• ZOTERO_API_KEY：您的Zotero API密钥（用于Web API）
• ZOTERO_LIBRARY_ID：您的Zotero库ID（用于Web API）
• ZOTERO_LIBRARY_TYPE：库类型（用户或组，默认：用户）

语义搜索：

• ZOTERO_EMBEDDING_MODEL：使用的嵌入模型（默认、openai、gemini）
• OPENAI_API_KEY：您的OpenAI API密钥（用于OpenAI嵌入）
• OPENAI_EMBEDDING_MODEL：OpenAI模型名称（text-embedding-3-small、text-embedding-3-large）
• OPENAI_BASE_URL：自定义OpenAI端点URL（可选，用于兼容API）
• GEMINI_API_KEY：您的Gemini API密钥（用于Gemini嵌入）
• GEMINI_EMBEDDING_MODEL：Gemini模型名称（models/text-embedding-004等）
• GEMINI_BASE_URL：自定义Gemini端点URL（可选，用于兼容API）

命令行选项

# 直接运行服务器
zotero-mcp serve

# 指定传输方法
zotero-mcp serve --transport stdio|streamable-http|sse

# 设置和配置
zotero-mcp setup --help                    # 获取设置选项的帮助
zotero-mcp setup --semantic-config-only    # 仅配置语义搜索
zotero-mcp setup-info                      # 显示MCP客户端的安装路径和配置信息

# 更新和维护
zotero-mcp update                          # 更新到最新版本
zotero-mcp update --check-only             # 检查更新但不安装
zotero-mcp update --force                  # 即使是最新的版本也强制更新

# 语义搜索数据库管理
zotero-mcp update-db                       # 更新语义搜索数据库（快速，仅元数据）
zotero-mcp update-db --fulltext             # 更新并提取全文（全面但较慢）
zotero-mcp update-db --force-rebuild       # 强制完全重建数据库
zotero-mcp update-db --fulltext --force-rebuild  # 使用全文提取重建
zotero-mcp db-status                       # 显示数据库状态和信息

# 一般
zotero-mcp version                         # 显示当前版本

📑 PDF注释提取

Zotero MCP包括高级PDF注释提取功能：

• 直接PDF处理：直接从PDF文件中提取注释，即使它们尚未被Zotero索引
• 增强搜索：搜索PDF注释和评论
• 图像注释支持：从PDF中提取图像注释
• 无缝集成：与Zotero的原生注释系统协同工作

为了实现最佳注释提取，强烈建议安装Zotero的Better BibTeX插件。注释相关功能主要在该插件存在的情况下进行了测试，并提供了增强的功能。

首次使用PDF注释功能时，必要的工具将自动下载。

📚 可用工具

🧠 语义搜索工具

• zotero_semantic_search：使用嵌入模型的AI驱动相似度搜索
• zotero_update_search_database：手动更新语义搜索数据库
• zotero_get_search_database_status：检查数据库状态和配置

🔍 搜索工具

• zotero_search_items：按关键词搜索您的库
• zotero_advanced_search：使用多个标准执行复杂搜索
• zotero_get_collections：列出集合
• zotero_get_collection_items：获取集合中的项目
• zotero_get_tags：列出所有标签
• zotero_get_recent：获取最近添加的项目
• zotero_search_by_tag：使用自定义标签过滤器搜索您的库

📚 内容工具

• zotero_get_item_metadata：获取详细元数据（支持通过format="bibtex"导出BibTeX）
• zotero_get_item_fulltext：获取全文内容
• zzotero_get_item_children：获取附件和笔记

📝 注释及笔记工具

• zotero_get_annotations：获取注释（包括直接PDF提取）
• zotero_get_notes：从您的Zotero库中检索笔记
• zotero_search_notes：在笔记和注释中搜索（包括PDF提取）
• zotero_create_note：为项目创建新笔记（测试版功能）

🔍 故障排除

一般问题

• 未找到结果：确保Zotero正在运行并且启用了本地API。您需要在Zotero首选项中启用“允许其他应用程序与此计算机上的Zotero通信”。
• 无法连接到库：如果使用Web API，请检查您的API密钥和库ID
• 全文不可用：确保您使用的是Zotero 7+以获得本地全文访问权限
• 本地库限制：某些功能（如标签、库修改）可能无法与本地JS API一起使用。考虑使用Web库设置以获得全部功能。（更多信息请参阅文档）
• 安装/搜索选项切换问题：更改安装方法或搜索选项导致的数据库问题通常可以通过zotero-mcp update-db --force-rebuild解决

语义搜索问题

• 运行update-db时出现“缺少必需的环境变量”：运行zotero-mcp setup以配置您的环境，或者CLI会自动从您的MCP客户端配置加载设置（例如，Claude Desktop）
• ChromaDB警告：更新到最新版本 - 已修复弃用警告
• 数据库更新耗时长：默认情况下，update-db是快速的（仅元数据）。对于全面索引全文，使用--fulltext标志。使用--limit参数进行测试：zotero-mcp update-db --limit 100
• 语义搜索返回无结果：确保数据库已通过zotero-mcp update-db初始化，并使用zotero-mcp db-status检查状态
• 搜索质量有限：为了获得更好的语义搜索结果，使用zotero-mcp update-db --fulltext索引全文内容（需要本地Zotero设置）
• OpenAI/Gemini API错误：验证您的API密钥是否正确设置并且有足够的信用/配额

更新问题

• 更新命令失败：检查您的互联网连接并尝试zotero-mcp update --force
• 更新后配置丢失：更新过程会自动保留配置，但可以在~/.config/zotero-mcp/中检查备份文件

📄 许可证

MIT