Zotero-MCP服务器

Name: Zotero-MCP服务器
Author: kujenga

作者：kujenga121 星标更新：2025-05-10

安装使用来源：spider==github.com

项目介绍

Zotero 的 Model Context Protocol 服务器

该项目是一个 Python 服务器，实现了 Model Context Protocol (MCP) 对于 Zotero，使您能够在 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 可能响应更快，但需要在运行 API 的同一台计算机上运行 Zotero 应用程序。要启用本地 API，请执行以下步骤：

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

[!重要] 要访问本地 API 中的 /fulltext 端点，该端点允许检索您图书馆中的项目全文内容，您需要安装一个 Zotero 测试版构建（截至 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 接口有网络连接。

开发

有关更改和贡献的信息。

克隆此存储库
使用 uv 安装依赖项，运行：uv sync
在项目根目录中创建一个 .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