Zotero MCP

🚀 Zotero 的 Model Context Protocol (MCP) 服务器

本项目是一个基于 Python 的服务器，实现了 Model Context Protocol (MCP) 与 Zotero 的集成。借助该服务器，您能够通过 AI 助手访问 Zotero 文献库，实现了一组功能虽小但实用的交互操作，可与 MCP 客户端 进行通信。

🚀 快速开始

此 MCP 服务器提供了以下工具，可通过任何 MCP 客户端或 MCP Inspector 发现和访问：

• zotero_search_items：使用文本查询在您的 Zotero 文献库中搜索项目。
• zotero_item_metadata：获取特定 Zotero 项目的详细元数据信息。
• zotero_item_fulltext：获取特定 Zotero 项目的全文内容（例如 PDF 文件）。

每个工具都会返回包含相关 Zotero 项目信息的格式化文本，AI 助手（如 Claude）可以按顺序使用它们，先搜索项目再获取其元数据或全文内容。

✨ 主要特性

• 实现 MCP 与 Zotero 的集成，支持通过 AI 助手访问 Zotero 文献库。
• 提供多个实用工具，方便对 Zotero 文献库进行搜索、获取元数据和全文内容。
• 支持与本地 API 或远程 Web API 通信，提供多种安装方式。

📦 安装指南

此服务器可以与 Zotero 的本地 API 或远程 Web API 通信，以下是两种安装方式：

方式一：使用 Docker 容器

在 mcp.json 文件中添加以下配置，替换占位符为您的实际 API 密钥和文献库 ID：

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER", // 替换为您的 API 密钥
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER", // 替换为您的文献库 ID
        "ghcr.io/kujenga/zotero-mcp:main"
      ]
    }
  }
}

方式二：本地安装

1. 克隆此仓库。
2. 使用 uv 安装依赖项，运行命令：

   uv sync
   

3. 在项目根目录创建一个 .env 文件，包含以下环境变量：

# 使用本地 API 时
ZOTERO_API=local

# 或使用远程 Web API 时
ZOTERO_API_KEY=your_api_key_here
ZOTERO_LIBRARY_ID=your_library_id_here

📚 详细文档

开发信息

要进行开发或贡献代码，请按照以下步骤操作：

1. 克隆此仓库。
2. 使用 uv 安装依赖项，运行命令：

   uv sync
   

3. 在项目根目录创建一个 .env 文件，包含所需的环境变量。

启动 MCP Inspector 进行本地开发：

npx @modelcontextprotocol/inspector uv run zotero-mcp

要测试与 Claude Desktop 的集成，请在您的 Claude 配置中添加以下内容，将 /path/to 替换为实际路径：

{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp",
      "env": {
        // 添加所需的环境变量配置
      }
    }
  }
}

运行测试

要运行测试套件，请运行命令：

uv run pytest

Docker 开发

使用以下命令构建容器镜像：

docker build . -t zotero-mcp:local

要通过 Inspector 测试容器，请运行命令：

npx @modelcontextprotocol/inspector \
    -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
    -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
    docker run --rm -i \
        --env ZOTERO_API_KEY \
        --env ZOTERO_LIBRARY_ID \
        zotero-mcp:local

相关文档

• https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
• https://github.com/modelcontextprotocol/python-sdk
• https://pyzotero.readthedocs.io/en/latest/
• https://www.zotero.org/support/dev/web_api/v3/start