Zotero MCP Lite

关键词

Zotero文献检索研究协作本地数据库全文提取

使用说明内容（Markdown格式）

  • 项目简介

    • Zotero MCP Lite 是一个面向 AI 研究场景的 MCP 服务器实现。它通过一组“工具”（Tools）和“提示模板”（Prompts）来向大型语言模型提供对 Zotero 文献库的读取、检索、注释以及笔记写作等能力，所有交互遵循 MCP（Model Context Protocol）规范，通过 JSON-RPC 风格的请求/响应进行通信。

  • 主要功能点

    • 9个原子工具（用于查询、读取、写入等）：
      1. zotero_search_items：在 Zotero 库中按关键词搜索条目
      2. zotero_get_recent：获取最近修改/添加的条目
      3. zotero_get_collections：列出并呈现收藏夹的层级结构
      4. zotero_get_collection_items：获取指定收藏夹中的条目
      5. zotero_search_annotations：跨文献检索 PDF 高亮与注释
      6. zotero_get_item_metadata：获取条目的完整元数据（可选包含 BibTeX）
      7. zotero_get_item_children：获取条目的附属物（附件、笔记）及注释
      8. zotero_get_item_fulltext：提取附件中论文的全文（含 Zotero 索引优先、必要时回退到 PyMuPDF）
      9. zotero_create_note：通过本地连接 API 创建笔记（可附带父项）
    • 4个研究提示（Prompts）：
      • knowledge_discovery、literature_review、comparative_review、bibliography_export
      • 提示从用户自定义文件夹加载（优先），如无则回退到程序包自带的默认模板。
    • 数据源与能力：
      • 本地 Zotero API（/api）与本地连接 API（/connector）进行只读/写入操作
      • 本地数据库（local_db）用于快速访问注释
      • PyMuPDF（用于全文提取的回退方案）如 Zotero 索引无内容
    • 安全与扩展性：
      • 会话与上下文信息通过 MCP 框架管理，支持多传输协议（stdio、SSE、WebSocket 等等，具体实现见仓库代码）
      • 提供对象化封装，便于客户端通过统一入口调用工具与渲染提示

  • 安装与运行步骤

    • 环境准备：确保已安装 Python3、以及本仓库依赖（如 fastmcp、pyzotero、mistune、httpx、PyMuPDF 等）。通常通过 pip 安装 requirements 即可。
    • 运行服务器：
      • 基本启动方式（命令行入口）：zotero-mcp serve
      • 常用传输模式：
        • stdio（默认，适合本地开发或 CLI 集成）
        • streamable-http（HTTP 传输，便于与远程客户端对接，需设置 host 和 port）
        • sse（Server-Sent Events，适合持续性推送）
    • 配置依赖项与环境变量：
      • ZOTERO_LIBRARY_ID/ ZOTERO_LIBRARY_TYPE：本地 Zotero 库标识与类型，默认本地库 0
      • Zotero 需要本地 API 与 Connector API 正常启用（通常在 Zotero 设置中开启本地 API）
      • 本地注释读取依赖本地数据库（local_db 模块会尝试检测 Zotero 数据库路径）
    • 流程要点
      • 先确保 Zotero 安装并能通过本地 API 访问
      • 启动 MCP 服务器后，客户端通过 MCP 协议发送请求，服务器执行对应工具并返回 JSON-RPC 风格的响应文本内容
      • 如需 BibTeX、全文提取等功能，请确保相应依赖可用（如 PyMuPDF）

  • 服务器配置（给 MCP 客户端的连接信息简述；JSON 配置示例以文字描述呈现，便于理解）

    • server name: Zotero MCP Lite
    • command: zotero-mcp
    • args: ["serve"]
    • 说明与注释：
      • 服务器名称用于 MCP 客户端在多服务器场景下区分
      • command 指向启动 MCP 服务的命令，当前仓库的入口点是 zotero-mcp 的 serve 子命令
      • args 为启动参数，通常为 ["serve"]，需要时可通过附加参数切换传输模式（如 --transport、--port、--host 等）
    • 运输选项（示例描述，不涉及代码）：
      • transport 模式可选：stdio、streamable-http、sse
      • 默认端口 8000，主机 localhost，HTTP 传输可自定义端口

  • 基本使用方法

    • 启动后，服务器就绪，MCP 客户端可以向该服务器发起请求，获取资源、调用工具、渲染提示模板
    • 常用工作流示例（由客户端发起的操作，与本仓库实现保持一致）
      • 通过 zotero_search_items 检索论文，随后获取元数据、全文或注释
      • 使用 zotero_get_item_metadata 获取论文元数据并可选生成 BibTeX
      • 使用 zotero_get_item_fulltext 获取论文全文做深入分析
      • 使用 zotero_create_note 将研究笔记以 Note 的形式保存到 Zotero
    • 维护与扩展
      • Prompts 与默认模板可通过 ~./zotero-mcp/prompts/ 自定义
      • 新增工具或扩展提示时，遵循 MCP 的装饰器接口即可被服务器加载

  • 运行与测试的简要提示

    • 本仓库包含完整的单元测试覆盖工具、客户端封装、以及本地数据库读取实现，确保服务器端功能完整可用
    • 运行时若遇依赖缺失，请安装相应的 Python 包，确保 Zotero 本地 API、Connector API、以及 PyMuPDF 等可用

  • 依赖与安全性说明

    • 本实现依赖本地 Zotero 环境，确保 Zotero Desktop 已经安装并开启本地 API
    • 针对写操作，使用本地 Connector API（需要 Zotero Desktop 支持）
    • 服务器端未在公开网络暴露敏感数据，默认本地测试与开发使用

服务器信息

访问项目