Zotero 的模型上下文协议服务器

本项目是一个 Python 服务器，它实现了 Zotero 的 模型上下文协议 (MCP)，使您可以在 AI 助手中访问您的 Zotero 文献库。 它的目的是实现与 Zotero 的一小部分但最有用的交互，以便与 MCP 客户端 一起使用。

<a href="https://glama.ai/mcp/servers/jknz38ntu4"> <img width="380" height="200" src="https://glama.ai/mcp/servers/jknz38ntu4/badge" alt="Zotero Server MCP server" /> </a>

功能

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

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

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

每个工具都会返回包含来自您的 Zotero 条目的相关信息的格式化文本，并且像 Claude 这样的 AI 助手可以按顺序使用它们，搜索条目，然后检索它们的元数据或文本内容。

安装

此服务器可以针对 Zotero 桌面应用程序提供的本地 API) 或通过 Zotero Web API 运行。 本地 API 的响应速度可能更快一些，但需要 Zotero 应用程序在同一台计算机上运行并启用 API。 要启用本地 API，请执行以下步骤：

1. 打开 Zotero 并打开“Zotero 设置”
2. 在“高级”选项卡下，选中标有“允许此计算机上的其他应用程序与 Zotero 通信”的框。

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

要使用 Zotero Web API，您需要在您的 Zotero 帐户设置中创建一个 API 密钥并找到您的文献库 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 和使用 uvx 的直接 python 安装一起使用，请将以下内容添加到 mcpServers 配置中：

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

如果您没有安装 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 的安装与本地 Zotero API 通信，但是您需要修改上面的命令以确保与 Zotero 应用程序的本地 API 接口建立网络连接。

开发

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

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

启动 MCP Inspector 以进行本地开发：

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": {
        // Whatever configuration is desired.
      }
    }
  }
}

运行测试

要运行测试套件：

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