zotero-brain-slim

Minimal Zotero MCP server（stdio）：库检索、八源论文发现、多级 PDF 下载瀑布、Zotero 导入。 不做解析与向量化——只负责「找到、下载、入库」。

工具面（6 个）

工具	说明
search_zotero_library	检索 Zotero 库（关键词/标题/DOI）
discover_papers	八源搜索（综合 4 + 分域 4），附在库标记
download_paper	7 级瀑布下载 PDF：缓存 → Unpaywall → arXiv → S2 → CORE → OpenAlex → Sci-Hub（默认关闭）
import_to_zotero	建条目 + linked_file 附件（PDF 留本地）+ 入 Collection
list_collections	列 Collection（可选带条目数）
create_collection	创建 Collection（同名复用）

数据源分域建议（Agent 路由）

discover_papers 的 sources 参数按提问方向只选 2-3 个相关源，避免八源全量轮询：

提问方向	建议源
综合 / 材料 / 工程 / 计算机	openalex + semantic_scholar（补充 crossref 核对元数据）
物理 / 数学 预印本	arxiv + openalex
天文 · 天体物理 · 空间科学	ads（需 token）+ arxiv
生物医学 · 生命科学	europepmc + openalex
开放获取全文	doaj + openalex（OA 链接直给）
欧盟项目 / 数据集关联	openaire

不传 sources 默认 openalex/arxiv/crossref/semantic_scholar 四综合源。

配置（全部经环境变量 / MCP env 传入）

变量	必填	说明
ZOTERO_MODE	否	auto（默认）/ local / web。auto：配了 Web 凭据走 Web（读写全功能），无凭据回落本地（只读）
ZOTERO_USER_ID / ZOTERO_API_KEY	auto/web 模式需要	Zotero Web API 凭据（本地模式可免）
ZOTERO_LIBRARY_TYPE	否	user（默认）或 group
ZOTERO_LOCAL	否	兼容旧配置：true 等价于 ZOTERO_MODE=local
UNPAYWALL_EMAIL	否	Unpaywall 认证邮箱。需真实邮箱——默认占位值（zotero-brain-slim@example.com）会使该下载级静默失效
OPENALEX_API_KEY	否	OpenAlex 免费 API key（已改 key 制，$1/天额度）
CORE_API_KEY	否	CORE 启用下载源
ADS_API_TOKEN	否	NASA ADS 源（天文/天体物理）；免费申请
SCIHUB_ENABLED	否	Sci-Hub 级开关（默认关闭；设 true 开启。下载瀑布最后一级，前面各级 OA 源命中不会走到它）
PROXY_URL	否	应用级 HTTP 代理（如 http://127.0.0.1:7890），留空直连

也支持同目录 .env 文件（本地调试用）。

本地模式前置条件（两个常见坑）

本地模式免 key、不限流，适合只读场景（搜库/查重）；写入操作必须走 Web API。使用本地模式需同时满足：

1. Zotero 桌面端必须正在运行——本地 API 由 Zotero 进程内的 HTTP server 提供， 未启动时连接直接失败；
2. 必须手动开启本地 API 开关：Zotero 菜单 编辑 → 设置 → 高级 → 杂项， 勾选 「允许其他应用程序通过本地 API 通信」（Allow other applications to communicate with Zotero），否则请求返回 403 - Local API is not enabled。

重要：Zotero 本地 API 是只读的（POST/PATCH/DELETE 一律 400 "Endpoint does not support method"，Zotero 的硬性设计）。因此凡涉及写入 （建文件夹、导入条目、挂附件）必须走 Web API + key。

ZOTERO_MODE=auto（默认）的策略：配置了 Web 凭据则整体走 Web（读写全功能， 避免"本地读、Web 写"的数据不一致观感）；未配置凭据且本地 API 可用则回落本地 只读模式（搜库/查重可用，写入会报明确指引）。

运行

<!-- 发布时替换为 Feplus2 -->

# uv / uvx（推荐）
uvx --from git+https://github.com/Feplus2/zotero-brain-slim zotero-brain-slim

# 本地开发
pip install -r requirements.txt
python mcp_server.py

作为 MCP server 注册（stdio，适用于 Claude Desktop 等通用 MCP 客户端）：

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/Feplus2/zotero-brain-slim", "zotero-brain-slim"],
  "env": {
    "ZOTERO_USER_ID": "…",
    "ZOTERO_API_KEY": "…"
  }
}

在 Better SageRead 中使用

本服务是 Better SageRead 文献工作流的一环：在 SageRead 的 MCP 管理器中注册为 stdio MCP server 即可。SageRead 的 env 支持 {{secret:NAME}} 占位符——spawn 进程前由 Rust 侧从系统凭据管理器取出同名条目并替换注入，凭据不写入配置文件：

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/Feplus2/zotero-brain-slim", "zotero-brain-slim"],
  "env": {
    "ZOTERO_USER_ID": "{{secret:ZOTERO_USER_ID}}",
    "ZOTERO_API_KEY": "{{secret:ZOTERO_API_KEY}}",
    "UNPAYWALL_EMAIL": "{{secret:UNPAYWALL_EMAIL}}"
  }
}

其余可选变量（ZOTERO_MODE、PROXY_URL、SCIHUB_ENABLED 等）按需添加， 明文值与 {{secret:...}} 占位符可混用。

代理与网络环境

本服务全部流量为 HTTPS API 请求，应用级 HTTP 代理即可，无需 TUN： 宿主应用注入的 HTTP_PROXY/HTTPS_PROXY 会被 httpx 自动遵循，或直接设 PROXY_URL。 境外源不可达时，下载瀑布会返回人工下载指引。

免责声明

Sci-Hub 级默认关闭（作为下载瀑布最后一级，前面各级 OA 源命中时不会走到它）。需要时可设 SCIHUB_ENABLED=true 显式开启；开启前请了解你所在地区的法律法规，使用者自行承担责任 （Keep the laws of your locality in mind）。本项目仅提供检索/下载/入库的工程实现， 不对任何下载源的合法性背书。

贡献

PR 欢迎：修 bug / 加下载源 / 改工具面。请保持「不做解析与向量化」的边界。