zotero-brain-slim

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

工具面（6 个）

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

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

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

Related MCP server: zotero-mcp

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

也支持同目录 .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 可用则回落本地 只读模式（搜库/查重可用，写入会报明确指引）。

运行

# 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 / 加下载源 / 改工具面。请保持「不做解析与向量化」的边界。