Model Context Protocol server for Zotero

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 Inspector 发现和访问。

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

安装

此服务既可以通过 Zotero 桌面应用提供的本地 API) 运行，也可以通过 Zotero Web API 运行。本地 API 的响应速度可能更快一些，但需要 Zotero 应用在同一台计算机上运行并启用 API。若要启用本地 API，请按以下步骤操作：

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

若要使用 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：文库类型（user 或 group，默认值：user）

uvx 搭配 Zotero 本地 API

若要通过 uvx 直接安装 Python 版并与 Claude Desktop 搭配使用，请将以下内容添加到 mcpServers 配置中：

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

@latest 说明符是可选的；有新版本时，它会获取最新版本。如果尚未安装 uvx，可以改用 pipx run，也可以在本地克隆此仓库，并按照下方开发部分的说明操作。

使用 Zotero Web API 的 Docker

如果要在 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 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

发布

1. 更新 pyproject.toml 和 server.json 中的版本号（两处：服务版本和包版本）。
2. 使用 make publish 发布到 PyPI。
3. 使用 make publish-mcp 将更新后的元数据发布到官方 MCP 注册表。如有需要，请先使用 mcp-publisher login github 完成身份验证。

Docker 开发

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

docker build . -t zotero-mcp:local

要使用 MCP 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
• LLM 可使用 https://modelcontextprotocol.io/llms-full.txt

附录：关于 Zotero API 的说明

条目元数据会根据 API 返回的字段渲染，而非依据固定列表。API 未返回的字段会被跳过，此服务不认识的字段则会显示在“其他字段”标题下，因此升级 Zotero 不会导致元数据被悄然丢弃。

这两个 API 有一点区别值得注意：本地 API 的快速搜索会索引引文键，而 Web API 不会。因此，即使数据中包含该字段，通过 Web API 搜索引文键也不会返回任何结果。