内容
# zotero-library-mcp
一个MCP服务器，允许Claude、Codex和ChatGPT通过DOI、arXiv ID或ISBN将论文和书籍添加到您的Zotero库中，并管理您的收藏、标签和项目。
该服务器支持这些客户端使用的两种MCP传输协议：
- **stdio** （默认）适用于Claude Code、Claude Desktop、Codex CLI/IDE和ChatGPT桌面应用程序
- **Streamable HTTP** 适用于托管的ChatGPT应用程序或任何远程MCP客户端
## 工具
### 添加论文
- **`add_paper_by_doi`** — 通过CrossRef解析DOI并将论文添加到Zotero（带有重复检测）
- **`add_papers_by_dois`** — 批量添加最多50篇论文
- **`add_paper_by_arxiv_id`** — 通过arXiv ID添加预印本（在可用时使用DOI，否则使用arXiv元数据）
- **`add_item_from_metadata`** — 从验证的手动元数据创建任何支持的Zotero项目类型
### 添加书籍
- **`add_book_by_isbn`** — 通过Open Library解析ISBN并将书籍添加到Zotero（带有重复检测）
### 搜索和浏览
- **`search_library`** — 按标题、作者、标签等搜索您的Zotero库（如果精确搜索返回的结果为0，则回落到模糊匹配）
- **`get_item_details`** — 查看任何项目的完整元数据
- **`get_recent_items`** — 列出最近添加的项目
- **`get_unfiled_items`** — 获取不在任何收藏中的项目
- **`search_fulltext`** — 搜索Zotero元数据和索引全文
- **`find_duplicates`** — 通过DOI、ISBN或标准化标题查找重复项目
- **`list_attachments`** — 列出每个附件并选择特定的PDF密钥
- **`health_check`** — 验证库凭证、访问和存储配置
### 阅读和注释
- **`get_item_fulltext`** — 从Zotero的索引或PDF返回有界的纯文本，不会泄露临时路径
- **`get_bibtex`** — 只读BibTeX/BibLaTeX导出项目、收藏或整个库
- **`save_bibtex`** — 将导出保存到授权的本地路径
- **`get_annotations`** — 列出论文PDF上的所有高亮和注释
- **`create_annotation`** — 在PDF中高亮文本段落（搜索精确文本，在Zotero阅读器中创建可见高亮，并返回预览图像进行验证）。智能重叠处理：精确副本更新现有注释；子段落自动获得对比高亮颜色。
- **`add_note`** — 向项目添加注释
- **`list_notes`** 、 **`update_note`** 、 **`delete_note`** — 管理现有注释
- **`update_annotation`** 、 **`delete_annotation`** — 编辑或删除注释
### 文件附件
- **`attach_file`** — 通过stdio或ChatGPT文件输入通过HTTP附加本地文件
- **`download_pdf`** — 返回远程安全的MCP文件资源
- **`save_pdf`** — 将PDF保存到授权的本地路径
### 收藏
- **`list_collections`** — 列出所有收藏（带有嵌套）
- **`create_collection`** — 创建新的收藏（可选地嵌套在父级下）
- **`get_collection_items`** — 浏览收藏中的项目
- **`add_to_collection`** — 将现有项目添加到收藏中
- **`remove_from_collection`** — 从收藏中删除项目（保留在库中）
- **`rename_collection`** 、 **`move_collection`** — 重新组织收藏
### 标签
- **`list_tags`** — 列出库中的所有标签
- **`add_tags`** — 向项目添加一个或多个标签（带有可选颜色）
- **`remove_tags`** — 从项目中删除标签
- **`delete_tags`** — 从整个库中删除标签
- **`set_tag_color`** — 为标签分配颜色（在Zotero的标签选择器中显示）
- **`rename_tag`** — 在库中的所有项目上重命名标签
- **`unset_tag_color`** — 删除标签颜色而不删除标签
### 验证
- **`verify_items`** — 重新检查近期项目与CrossRef的匹配，以捕获错误的DOI或标题不匹配
### 删除
- **`delete_item`** — 永久删除库中的项目
- **`delete_collection`** — 永久删除收藏
- **`trash_item`** 、 **`restore_item`** — 优先使用可逆的回收站操作进行常规清理
服务器还公开了ChatGPT公司知识和深度研究使用的标准只读 **`search`** 和 **`fetch`** 工具形状。
## 先决条件
1. [Zotero账户](https://www.zotero.org/user/register)
2. 带有 **写入** 权限的Zotero API密钥： https://www.zotero.org/settings/keys
3. 您的Zotero **库ID** （在同一页面显示，或在您的个人资料URL中）
4. 安装的 [uv](https://docs.astral.sh/uv/)
## 快速入门
### Codex和ChatGPT桌面应用程序
Codex和ChatGPT桌面应用程序在同一Codex主机上共享MCP配置。添加服务器一次：
```bash
codex mcp add zotero \
--env ZOTERO_LIBRARY_ID=您的库ID \
--env ZOTERO_API_KEY=您的API密钥 \
-- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp
```
然后重启Codex或ChatGPT桌面应用程序。在Codex中使用 `/mcp` 确认 `zotero` 已连接。在ChatGPT桌面版中，打开 **设置 → MCP服务器** 以查看相同的服务器。
对于WebDAV存储，请添加在 [WebDAV示例](#webdav-setup) 中显示的三个 `ZOTERO_WEBDAV_*` 值。如果桌面应用程序找不到 `uvx`，请用 `which uvx` 返回的完整路径替换它。
您也可以直接在 `~/.codex/config.toml` 中配置服务器：
```toml
[mcp_servers.zotero]
command = "/full/path/to/uvx"
args = ["--from", "git+https://github.com/RaulSimpetru/zotero-library-mcp", "zotero-mcp"]
env_vars = ["ZOTERO_LIBRARY_ID", "ZOTERO_API_KEY", "ZOTERO_LIBRARY_TYPE", "CROSSREF_MAILTO", "ZOTERO_WEBDAV_URL", "ZOTERO_WEBDAV_USER", "ZOTERO_WEBDAV_PASSWORD"]
startup_timeout_sec = 30
tool_timeout_sec = 120
```
使用 `env_vars` 启动Codex/ChatGPT时，请从包含这些变量的环境中启动。如果您故意将它们的值存储在配置文件中，请使用 `[mcp_servers.zotero.env]`。
### Claude Code
```bash
claude mcp add zotero \
-e ZOTERO_LIBRARY_ID=您的库ID \
-e ZOTERO_API_KEY=您的API密钥 \
-- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp
```
#### WebDAV设置
要使用WebDAV文件存储（例如Synology、Nextcloud），请包含WebDAV变量：
```bash
claude mcp add zotero \
-e ZOTERO_LIBRARY_ID=您的库ID \
-e ZOTERO_API_KEY=您的API密钥 \
-e ZOTERO_WEBDAV_URL=https://您的WebDAV服务器.com \
-e ZOTERO_WEBDAV_USER=您的用户名 \
-e ZOTERO_WEBDAV_PASSWORD=您的密码 \
-- uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp
```
### Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"zotero": {
"command": "/full/path/to/uvx",
"args": ["--from", "git+https://github.com/RaulSimpetru/zotero-library-mcp", "zotero-mcp"],
"env": {
"ZOTERO_LIBRARY_ID": "您的库ID",
"ZOTERO_API_KEY": "您的API密钥",
"ZOTERO_WEBDAV_URL": "https://您的WebDAV服务器.com",
"ZOTERO_WEBDAV_USER": "您的用户名",
"ZOTERO_WEBDAV_PASSWORD": "您的密码"
}
}
}
}
```
> **注意：** Claude Desktop不继承shell的PATH，因此您需要使用`which uvx`在终端中找到`uvx`的完整路径。
### 网页版ChatGPT（Apps SDK / 开发模式）
网页版ChatGPT连接到HTTPS Streamable HTTP端点。使用HTTP传输启动服务器，然后通过 [安全MCP隧道](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) 或另一个身份验证的HTTPS部署使其可访问：
```bash
ZOTERO_LIBRARY_ID=您的库ID ZOTERO_API_KEY=您的API密钥 \
uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp \
--transport streamable-http \
--host 127.0.0.1 \
--port 8000 \
--allowed-host 您的隧道.example.com
```
MCP端点是 `https://您的隧道.example.com/mcp`。在ChatGPT中启用开发者模式，创建一个开发者模式应用程序，并输入该URL作为MCP服务器URL。请参阅OpenAI的 [从ChatGPT连接](https://developers.openai.com/apps-sdk/deploy/connect-chatgpt) 指南，了解当前的UI流程。
> **安全性：** 最安全的个人设置是使用OpenAI安全MCP隧道，MCP服务器绑定到环回地址。HTTP模式默认禁用所有服务器路径读取和写入。 `attach_file` 接受ChatGPT授权的文件对象，而 `download_pdf` 返回不透明的MCP资源链接。安全注释是批准提示，而不是授权边界。
对于公共单库部署，请配置外部OAuth 2.1身份提供程序。服务器根据其JWKS端点验证JWT访问令牌：
```bash
export ZOTERO_MCP_OAUTH_ISSUER=https://auth.example.com
export ZOTERO_MCP_OAUTH_RESOURCE=https://zotero.example.com
export ZOTERO_MCP_OAUTH_JWKS_URL=https://auth.example.com/.well-known/jwks.json
export ZOTERO_MCP_OAUTH_SCOPES=zotero:read,zotero:write
```
授权服务器必须发布OAuth/OIDC发现元数据，支持带有PKCE的MCP OAuth 2.1流程，颁发 `ZOTERO_MCP_OAUTH_RESOURCE` 的令牌，并包含配置的作用域。请参阅OpenAI的 [身份验证指南](https://developers.openai.com/apps-sdk/build/auth)。对于仅在身份验证网关后进行测试，请使用 `--allow-unauthenticated-http` 显式确认未经身份验证的非环回监听器。
此过程仍使用一个服务器端Zotero库密钥。真正的多用户服务必须将验证的OAuth身份映射到单独的Zotero凭证，并强制执行按用户授权；该部署架构故意不在此个人服务器包之外。
如果HTTP部署确实需要服务器路径，请仅在限定根目录中启用它们：
```bash
zotero-mcp --transport streamable-http \
--allow-server-files \
--file-root /srv/zotero-mcp/exports
```
HTTP启动设置也可以作为环境变量提供：
| CLI选项 | 环境变量 | 默认值 |
|------------|----------------------|---------|
| `--transport` | `ZOTERO_MCP_TRANSPORT` | `stdio` |
| `--host` | `ZOTERO_MCP_HOST` | `127.0.0.1` |
| `--port` | `ZOTERO_MCP_PORT` 或 `PORT` | `8000` |
| `--http-path` | `ZOTERO_MCP_HTTP_PATH` | `/mcp` |
| `--allowed-host` | `ZOTERO_MCP_ALLOWED_HOSTS` （逗号分隔） | 本地主机 |
| `--allowed-origin` | `ZOTERO_MCP_ALLOWED_ORIGINS` （逗号分隔） | 本地源 |
| `--stateless-http` | `ZOTERO_MCP_STATELESS_HTTP` | `false` |
| `--allow-unauthenticated-http` | `ZOTERO_MCP_ALLOW_UNAUTHENTICATED_HTTP` | `false` |
| `--allow-server-files` | `ZOTERO_MCP_ALLOW_SERVER_FILES` | HTTP模式下为`false` |
| `--file-root` | `ZOTERO_MCP_FILE_ROOTS` （逗号分隔） | 无 |
### 独立运行
```bash
ZOTERO_LIBRARY_ID=您的库ID ZOTERO_API_KEY=您的API密钥 \
uvx --from git+https://github.com/RaulSimpetru/zotero-library-mcp zotero-mcp
```
## 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `ZOTERO_LIBRARY_ID` | 是 | 您的Zotero用户或组库ID |
| `ZOTERO_API_KEY` | 是 | 具有读写权限的API密钥 |
| `ZOTERO_LIBRARY_TYPE` | 否 | `user` （默认）或 `group` |
| `CROSSREF_MAILTO` | 否 | 您的CrossRef礼貌池电子邮件（更快的API访问） |
| `UNPAYWALL_EMAIL` | 否 | 开放访问PDF查找的联系电子邮件（默认为 `CROSSREF_MAILTO`） |
| `ZOTERO_WEBDAV_URL` | 否 | WebDAV URL用于文件存储（例如 `https://dav.example.com`） |
| `ZOTERO_WEBDAV_USER` | 否 | WebDAV用户名 |
| `ZOTERO_WEBDAV_PASSWORD` | 否 | WebDAV密码 |
| `ZOTERO_MCP_OAUTH_ISSUER` | 否 | 受保护的HTTP部署的外部OAuth/OIDC颁发者URL |
| `ZOTERO_MCP_OAUTH_RESOURCE` | 否 | 规范的HTTPS MCP资源/受众URL |
| `ZOTERO_MCP_OAUTH_JWKS_URL` | 否 | 用于验证JWT访问令牌的JWKS URL |
| `ZOTERO_MCP_OAUTH_SCOPES` | 否 | 以逗号分隔的必需作用域（默认为读取和写入） |
| `ZOTERO_MCP_FILE_ROOTS` | 否 | 启用HTTP服务器路径时的允许根目录（逗号分隔） |
> **注意：** 如果设置了所有三个 `ZOTERO_WEBDAV_*` 变量，则文件附件将上传到您的WebDAV服务器，而不是Zotero的内置存储。服务器会自动在基本URL后追加 `/zotero`，以匹配Zotero Desktop的行为。
## 升级到 0.8
两个路径写入操作与其只读对应操作分离，以便远程客户端可以应用正确的安全审批：
- `get_bibtex(save_path=...)` 现已成为 `save_bibtex(save_path=...)`；`get_bibtex` 仅返回数据。
- `download_pdf(save_path=...)` 现已成为 `save_pdf(save_path=...)`；`download_pdf` 返回不透明的MCP资源链接。
现有的 `get_bibtex` 和 `download_pdf` 的只读调用继续有效。
### 0.8.1
- PDF和注释预览资源现在在客户端读取时保留其精确的MIME类型。
- PDF下载报告进度并返回明确的WebDAV超时错误。
- `health_check` 在不修改库的情况下报告API密钥写入权限。
- 服务器指令更短，减少了重复的客户端上下文使用。
## 工作原理
1. 您提供DOI、arXiv ID或ISBN
2. 服务器查询相应的API以获取完整元数据：
- **DOI** → [CrossRef API](https://api.crossref.org)
- **arXiv ID** → [arXiv API](https://info.arxiv.org/help/api/) （如果存在DOI，则使用CrossRef备用）
- **ISBN** → [Open Library API](https://openlibrary.org/developers/api)
3. 元数据映射到Zotero的项目格式（标题、作者、期刊/出版商、日期等）
4. 项目通过 [Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/start) 创建在您的Zotero库中
## 许可证
MIT
mcp-name: io.github.RaulSimpetru/zotero-library-mcp
