Zotero的Model Context Protocol服务器

本项目是一个Python服务器，实现了针对Zotero的Model Context Protocol (MCP)，让您能够在AI助手中访问您的Zotero文献库。它旨在实现一组与Zotero交互的小型但功能强大的工具集，供MCP客户端使用。

功能特性

该MCP服务器提供以下工具：

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

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

每个工具都会返回包含您Zotero条目相关信息的格式化文本，AI助手（如Claude）可以依次使用它们，先搜索条目，然后检索其元数据或文本内容。

安装

该服务器可以通过Zotero桌面应用程序提供的本地API或通过Zotero Web API运行。本地API响应速度可能更快，但需要Zotero应用程序在与API相同的计算机上运行并启用。要启用本地API，请按照以下步骤操作：

1. 打开Zotero并打开"Zotero设置"
2. 在"高级"选项卡下，勾选"允许此计算机上的其他应用程序与Zotero通信"复选框

[!重要] 要访问本地API上的/fulltext端点（允许检索您文献库中条目的完整内容），您需要安装Zotero Beta版本（截至2025-03-30）。一旦7.1版本发布，这将不再需要。更多信息请参见https://github.com/zotero/zotero/pull/5004。如果您不想这样做，请使用Web API。

要使用Zotero Web API，您需要创建一个API密钥并在您的Zotero账户设置中找到您的文献库ID（通常是您的用户ID）：https://www.zotero.org/settings/keys

以下是可用的配置选项：

• ZOTERO_LOCAL=true：使用本地Zotero API（默认：false，请参见下面的说明）
• ZOTERO_API_KEY：您的Zotero API密钥（本地API不需要）
• ZOTERO_LIBRARY_ID：您的Zotero文献库ID（用户文献库的用户ID，本地API不需要）
• ZOTERO_LIBRARY_TYPE：文献库类型（用户或组，默认：用户）

使用uvx与本地Zotero API

要将其与Claude Desktop和直接Python安装（使用uvx）一起使用，请将以下内容添加到mcpServers配置中：

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["--upgrade", "zotero-mcp"],
      "env": {
        "ZOTERO_LOCAL": "true",
        "ZOTERO_API_KEY": "",
        "ZOTERO_LIBRARY_ID": ""
      }
    }
  }
}

--upgrade标志是可选的，当有新版本可用时会拉取最新版本。如果您没有安装uvx，可以使用pipx run代替，或者克隆此仓库并在本地使用下面的开发部分中的说明。

使用Docker与Zotero Web API

如果您想在Docker容器中运行此MCP服务器，可以使用以下配置，插入您的API密钥和文献库ID：

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER",
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
        "ghcr.io/kujenga/zotero-mcp:main"
      ],
    }
  }
}

要更新到较新版本，请运行docker pull ghcr.io/kujenga/zotero-mcp:main。也可以使用基于Docker的安装来与本地Zotero API通信，但需要修改上述命令以确保与Zotero应用程序的本地API接口有网络连接。

开发

关于进行更改和为项目做出贡献的信息。

1. 克隆此仓库
2. 使用uv安装依赖项，运行：uv sync
3. 在项目根目录中创建一个.env文件，包含上述环境变量

启动MCP检查器进行本地开发：

npx @modelcontextprotocol/inspector uv run zotero-mcp

要在Claude Desktop上测试本地仓库，请在此目录的shell中运行echo $PWD/.venv/bin/zotero-mcp，然后在您的Claude Desktop配置中设置以下内容：

{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp"
      "env": {
        // 任何所需的配置。
      }
    }
  }
}

运行测试

要运行测试套件：

uv run pytest

Docker开发

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

docker build . -t zotero-mcp:local

要使用MCP检查器测试容器，请运行以下命令：

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
• https://modelcontextprotocol.io/llms-full.txt 可供大型语言模型使用