urschrei/pyzotero · 上手攻略

  • 仓库：urschrei/pyzotero
  • 链接：https://github.com/urschrei/pyzotero
  • 分类：academic-writing · zotero-integration
  • 作者：Tom
  • 更新：2026-08-16

这是什么

Pyzotero 是 Zotero API 的 Python 客户端，由 Zotero 社区维护，支持对个人库和团体库进行完整的增删改查操作。它提供 Python 库、CLI 工具和 MCP 服务器三种使用形态，适合需要将 Zotero 文献管理自动化接入 AI 工作流的用户。

解决什么问题：Zotero 的 Web API 功能强大但需要手动操作，Pyzotero 让你用 Python 脚本或命令行直接操控 Zotero 库——批量导入文献、按标签筛选、做笔记、同步 PDF 全文搜索，以及通过 MCP 让 LLM 直接访问本地文献库。

快速安装

Python 库安装

# uv（推荐）
uv add pyzotero

# pip
pip install pyzotero

# conda
conda install conda-forge::pyzotero

带 CLI 的安装

uv add "pyzotero[cli]"
pip install "pyzotero[cli]"

带 MCP 服务器的安装

uv add "pyzotero[mcp]"
pip install "pyzotero[mcp]"

# 或作为独立工具安装
uv tool install "pyzotero[mcp]"

不安装直接运行 CLI

uvx --from "pyzotero[cli]" pyzotero search -q "machine learning"
pipx run --spec "pyzotero[cli]" pyzotero search -q "machine learning"

核心用法

初始化与认证

from pyzotero import Zotero

# 获取方法：
# 个人库：https://www.zotero.org/settings/keys → Your userID for use in API calls
# 团体库：打开团体页面，hover 设置链接，URL 中 /groups/ 后的整数即为 ID
# API Key：https://www.zotero.org/settings/keys/new

zot = Zotero(
    library_id,    # int，个人库 userID 或团体库 ID
    library_type,   # 'user' 或 'group'
    api_key        # 你的 Zotero API key
)

# local=True 用于只读访问本地 Zotero（需要 Zotero 7 + 开启远程 API）
items = zot.top(limit=5)
for item in items:
    print(f"{item['data']['itemType']} | {item['data']['key']}")

CLI 搜索

# 搜索顶级条目标题和元数据
pyzotero search -q "machine learning"

# 全文搜索（含 PDF 内容）
pyzotero search -q "climate change" --fulltext

# 按条目类型筛选
pyzotero search -q "methodology" --itemtype book --itemtype journalArticle

# 在指定收藏集中搜索
pyzotero search --collection ABC123 -q "test"

# 输出 JSON（机器处理）
pyzotero search -q "climate" --json

# 列出所有收藏集
pyzotero listcollections

# 列出可用条目类型
pyzotero itemtypes

⚠️ 全文搜索注意：--fulltext 搜索 PDF 附件内容时，CLI 会自动检索匹配附件的父级文献条目，返回的是标准书目记录而非原始 PDF。

MCP 服务器（Claude Desktop 集成）

在 Claude Desktop 配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或对应路径添加：

{
  "mcpServers": {
    "zotero": {
      "command": "pyzotero-mcp"
    }
  }
}

或者不安装，用 uvx 方式：

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["--from", "pyzotero[mcp]", "pyzotero-mcp"]
    }
  }
}

MCP 工具列表

Zotero 本地库工具：

工具 说明
search 按查询、类型、收藏集、标签或全文搜索
get_item 按 key 获取单条 Zotero 条目
get_children 获取条目的子项（附件、笔记）
list_collections 列出所有收藏集
list_tags 列出所有标签（可按收藏集筛选）
get_fulltext 获取 PDF 等附件的全文内容

Semantic Scholar 集成工具：

工具 说明
find_related 用 SPECTER2 嵌入找相似论文
get_citations 找引用了某论文的文献
get_references 找某论文引用的文献
search_semantic_scholar 搜索 Semantic Scholar 论文索引

⚠️ Semantic Scholar 工具默认会检查结果是否已在本地图馆中（check_library=True）。

典型适用场景

  1. 学术写作自动化：批量导入文献、整理标签、提取 PDF 全文内容供 AI 阅读。
  2. AI 研究助手：MCP 服务器让 Claude Desktop 直接查询本地 Zotero 库，找相似论文、查引用关系。
  3. 文献综述构建：用 find_related + get_citations 构建论文引用图谱。
  4. 跨平台同步：通过 API 访问非本地 Zotero 库，适合多设备用户。
  5. CLI 快速检索：不用打开 Zotero App，在终端直接搜文献标题、作者、标签。

坑与注意

  1. Zotero API Key 权限：个人库和未公开的团体库需要 API Key；公开团体库可不带 key 访问。
  2. Zotero 7 本地 API：MCP 和 CLI 的 local=True 模式要求 Zotero 7 在设置中开启"Allow other applications on this computer to communicate with Zotero"。
  3. 全文搜索依赖 PDF 索引：只有 Zotero 中有 PDF 附件且已建立全文索引的文献才能被 --fulltext 搜到。
  4. API 速率限制：Zotero API 有请求频率限制，高频操作建议加延时或用 local=True 旁路。
  5. Pyzotero v1.0 Semver：v1.0 后遵循 Semver，API 变更会升主版本号，升级前注意 changelog。
  6. MCP CLI 路径：直接运行 pyzotero-mcp 需要 PATH 中有对应命令，建议用 uvx 或 pipx 隔离环境。
  7. Semantic Scholar 工具的 check_library：默认开启，会额外查询本地库，可能增加延迟。

与同类对比

维度 Pyzotero zotero-better-bibtex citekey-py RJafroc
核心功能 Zotero API 客户端 BibTeX 导出/同步 引用 key 生成 ROC 分析
Python 支持 ✅ 原生 ❌（JS 插件） ✅ ❌
CLI 工具 ✅ ❌ ❌ ❌
MCP 服务器 ✅ ❌ ❌ ❌
全文搜索 ✅（需 PDF 索引） ❌ ❌ ❌
Semantic Scholar 集成 ✅ ❌ ❌ ❌
维护状态 活跃（Blue Oak 许可证） 活跃（Zotero 插件） 低活跃 低活跃

Pyzotero 的核心优势：纯 Python + 完整 API 覆盖 + MCP 生态接入，是目前将 Zotero 接入 AI 工作流最直接的方案。

一句话推荐结论

Pyzotero 是 Zotero 官方 API 最完整的 Python 封装，适合学术写作者和 AI 应用开发者将 Zotero 文献库无缝接入自动化和 LLM 工作流。

最小可跑命令

# 前置：Python 3.9+，Zotero 7（本地模式），API Key
uv add pyzotero

# Python 示例（需替换为真实 library_id / library_type / api_key）
python3 -c "
from pyzotero import Zotero
zot = Zotero(12345, 'user', 'your_api_key_here')
items = zot.top(limit=3)
for item in items:
    print(item['data']['itemType'], '|', item['data'].get('title', 'N/A'))
"

# CLI 搜索（无需 key，仅搜索公开库）
uvx --from 'pyzotero[cli]' pyzotero search -q 'deep learning' --limit 3

⚠️ Python 版本：官方文档未注明最低版本，推测支持 Python 3.9+；uv sync 构建基于 pyproject.toml，具体以 pyproject.toml 为准。

来源

  • https://github.com/urschrei/pyzotero（README + CONTRIBUTING.md）
  • https://pyzotero.readthedocs.org（完整文档）
  • https://pypi.org/project/Pyzotero/