# zotero-local-mcp

**零配置、只读的 Zotero 本地 MCP Server —— 让所有主流 AI 都能用你的 Zotero 文献库。**

![Python](https://img.shields.io/badge/python-3.10%2B-blue) ![License](https://img.shields.io/badge/license-MIT-green) ![MCP](https://img.shields.io/badge/protocol-MCP-purple)

让 Claude、Cursor、Windsurf、VS Code、Codex、Gemini CLI、Cherry Studio 等 AI 助手直接**检索、浏览、引用**你本机的 Zotero 文献库。
不需要申请 API Key,不需要装任何 Zotero 插件,所有数据都留在你自己的电脑上。

```jsonc
// 大多数客户端只需这几行,然后就能问:
// 「帮我找库里关于 deep learning 的论文」「给这篇生成 BibTeX」
{
  "mcpServers": {
    "zotero": { "command": "zotero-local-mcp" }
  }
}
```

## ✨ 特点

- **零配置** —— 不申请 Zotero API Key,不装 Better BibTeX 等任何插件
- **纯本地** —— 通过 Zotero 7 内置的本地 API(`127.0.0.1:23119`)工作,数据不出电脑
- **广泛兼容** —— 同时支持 stdio(桌面客户端)与 Streamable HTTP / SSE(Web 类客户端)两种传输
- **引用直达** —— `zotero_bibtex` 优先使用 Zotero 自带的 BibTeX 导出,失败时自动退回内置简化生成器
- **离线友好** —— Zotero 没开会返回清晰的中英文排查指引,而不是晦涩报错

## 🧩 客户端兼容性

| 客户端 | 传输方式 | 支持 |
|---|---|---|
| Claude Desktop | stdio | ✅ |
| Claude Code | stdio | ✅ |
| Cursor | stdio | ✅ |
| Windsurf | stdio | ✅ |
| VS Code(GitHub Copilot) | stdio | ✅ |
| Codex CLI / Codex 桌面版 | stdio | ✅ |
| Gemini CLI | stdio | ✅ |
| ZCode | stdio | ✅ |
| Cline / Roo Code(VS Code 插件) | stdio | ✅ |
| Cherry Studio | stdio | ✅ |
| Open WebUI / LobeChat / Dify 等 Web 端 | Streamable HTTP / SSE | ✅ |

任何支持 MCP 协议(stdio 或 Streamable HTTP)的客户端都可以接入。

## 🧰 提供的工具(8 个)

| 工具 | 作用 |
|---|---|
| `zotero_status` | 检查与本地 Zotero 的连接状态 |
| `zotero_search` | 关键词搜索文献(支持按标签过滤) |
| `zotero_recent` | 列出最近添加/修改的文献 |
| `zotero_collections` | 列出所有分类(集合) |
| `zotero_collection_items` | 浏览某个分类下的条目 |
| `zotero_item` | 查看条目详情(摘要、DOI、附件、笔记数) |
| `zotero_tags` | 列出文献库用过的标签 |
| `zotero_bibtex` | 为一个或多个条目生成 BibTeX |

## 📦 安装

```bash
# 方式一:用 uv 运行(推荐,自动解决 Python 环境,无需手动装 Python)
uvx zotero-local-mcp

# 方式二:pip / pipx 安装
pip install zotero-local-mcp
pipx install zotero-local-mcp
```

从源码安装:

```bash
git clone https://github.com/Zhang-rgb-r/zotero-local-mcp
cd zotero-local-mcp
pip install -e .
```

**前置条件**:Zotero 7 或更高版本正在运行。Zotero 7 的本地 API 默认开启;如果没有,请在
「编辑 → 设置 → 高级」中勾选**「允许这台计算机上的其他应用程序与 Zotero 通信」**。

## 🔧 各客户端接入配置

以下配置任选其一。`zotero-local-mcp` 需在 PATH 中(pipx/pip 安装后即有);
如果用 uvx,把 `command` 换成 `uvx`、`args` 换成 `["zotero-local-mcp"]` 即可免装 Python。

**Claude Desktop**(`%APPDATA%\Claude\claude_desktop_config.json`,macOS 为
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "zotero": { "command": "zotero-local-mcp" }
  }
}
```

**Cursor**:设置 → MCP → Add MCP Server,或编辑 `~/.cursor/mcp.json`,内容同上。

**Windsurf**(`~/.codeium/windsurf/mcp_config.json`):内容同上。

**Cline / Roo Code**(VS Code 内 MCP 设置文件 `cline_mcp_settings.json`):内容同上。

**Cherry Studio**:设置 → MCP 服务器 → 添加,类型选 **STDIO**,命令填 `zotero-local-mcp`。

**Claude Code**(终端一条命令):

```bash
claude mcp add zotero -- zotero-local-mcp
```

**VS Code(GitHub Copilot)**(工作区 `.vscode/mcp.json`):

```json
{
  "servers": {
    "zotero": {
      "command": "zotero-local-mcp"
    }
  }
}
```

**Codex CLI**(`~/.codex/config.toml`):

```toml
[mcp_servers.zotero]
command = "zotero-local-mcp"
```

**Gemini CLI**(`~/.gemini/settings.json`):

```json
{
  "mcpServers": {
    "zotero": { "command": "zotero-local-mcp" }
  }
}
```

**ZCode**:在 MCP 设置中添加同样的 `mcpServers` 结构,或参考客户端文档以 `/mcp` 方式添加。

**Open WebUI / LobeChat / Dify 等 Web 端**(先以 HTTP 模式启动服务):

```bash
zotero-local-mcp --transport http --port 8321
# SSE 模式:zotero-local-mcp --transport sse --port 8321
```

然后在客户端里添加远程 MCP 地址:`http://127.0.0.1:8321/mcp`(SSE 模式为 `http://127.0.0.1:8321/sse`)。

💡 从源码安装时,把上面各配置里的 `command` 换成你的解释器路径、加 `args: ["-m", "zotero_local_mcp"]` 即可。
Zotero 不在默认地址时,可通过环境变量覆盖:`ZOTERO_LOCAL_URL=http://127.0.0.1:23119`。

## 💬 装好之后可以怎么用

- 「我库里有没有关于 transformer 注意力机制的论文?」
- 「列出最近一个月加进来的文献」
- 「我"强化学习"分类下都有什么?」
- 「给刚才那篇生成 BibTeX,我要贴进 LaTeX」

## 🧠 工作原理

[Zotero 7](https://www.zotero.org/) 在本机 `127.0.0.1:23119` 提供了一个只读 HTTP API,
URL 结构与 [api.zotero.org](https://www.zotero.org/support/dev/client_coding/python) 一致。
本项目是它与 [Model Context Protocol](https://modelcontextprotocol.io) 之间的轻量桥梁:
把 MCP 工具调用翻译成对本地 API 的请求,并整理成对 AI 友好的紧凑输出。
项目为只读,不会修改你的文献库。

## 🆚 与其他方案对比

| 方案 | 需要 API Key | 需要插件 | 说明 |
|---|---|---|---|
| **zotero-local-mcp**(本项目) | ❌ | ❌ | 本地库、只读、零配置、stdio+HTTP 双模式 |
| 基于 Zotero Web API 的方案 | ✅ | ❌ | 读写同步库,需去 zotero.org 申请密钥 |
| 基于 Better BibTeX debug-bridge 的方案 | ❌ | ✅ | 引用能力更强,但配置门槛高 |

## 🗺 Roadmap

- [ ] 写入支持(通过 connector 接口添加条目)
- [ ] PDF 注释/高亮导出
- [ ] 与 Better BibTeX 集成,输出 CSL 引用格式
- [ ] 上架 PyPI,支持 `uvx zotero-local-mcp` 一行运行
- [ ] 演示 GIF

## 🛠 本地开发

```bash
python -m venv .venv
.venv\Scripts\pip install -e .
.venv\Scripts\python scripts\e2e_check.py     # stdio 端到端测试(建议开着 Zotero 跑)
.venv\Scripts\python -m zotero_local_mcp --transport http --port 8321   # 起HTTP服务
.venv\Scripts\python scripts\http_probe.py    # 验证 HTTP 传输
.venv\Scripts\python tests\mock_zotero_api.py # 没有 Zotero?先起模拟 API 再跑 e2e
```

## English

**zotero-local-mcp** is a zero-config, read-only [MCP](https://modelcontextprotocol.io) server
that lets AI assistants (Claude, Cursor, Windsurf, VS Code, Codex, Gemini CLI, ...) search and
cite your **local** Zotero 7 library — no API key, no plugins, everything stays on your machine.
Ships both stdio (desktop clients) and Streamable HTTP / SSE (web clients) transports.

```bash
pip install zotero-local-mcp
# or run without installing: uvx zotero-local-mcp
# web clients: zotero-local-mcp --transport http --port 8321  ->  http://127.0.0.1:8321/mcp
```

Requirements: Zotero 7 running locally. 8 tools: status / search / recent / collections /
collection items / item detail / tags / BibTeX.

## 📄 License

[MIT](LICENSE)