项目背景： Zotero 的 Model Context Protocol (MCP) 服务器

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

功能

此 MCP 服务器提供了以下工具：

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

这些工具可以通过任何 MCP 客户端或通过 MCP Inspector 发现和访问。

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

安装

此服务器可以与 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