内容
# Zotero 助手 MCP — 远程 (Cloudflare Workers)
一个用于读取、写入和管理 Zotero 库中条目的远程 MCP 服务器，部署在 Cloudflare Workers 上。每个用户都将自己的服务器部署到自己的 Cloudflare 账户中 — 没有共享基础设施，超出 Cloudflare 慷慨的免费层级后无需额外付费。
## 快速开始
您需要 [Node.js](https://nodejs.org/) 18+、一个 [Zotero 账户](https://www.zotero.org/) 和一个 [Cloudflare 账户](https://dash.cloudflare.com/sign-up)（免费层级 — 无需信用卡）。
```sh
git clone https://github.com/upascal/zotero-assistant-mcp-remote.git
cd zotero-assistant-mcp-remote
npm install
npm run setup
```
这将打开一个基于浏览器的设置向导，引导您完成：
1. **Zotero 凭证** — 输入您的库 ID 和 API 密钥（带有“测试连接”按钮以进行验证）
2. **Cloudflare 登录** — 向导检测您是否已登录。如果不是，它将为您打开 Cloudflare 登录页面。
3. **部署** — 一键部署 Worker，设置您的机密，并生成一个安全的 bearer token。
部署后，向导将显示您的安全 MCP URL，并为您提供三种连接方式：
| 方法 | 最适合 |
|--------|----------|
| **Claude Desktop UI** | 在设置 → 连接器 → 添加自定义连接器中粘贴单个 URL |
| **JSON 配置** | 手动编辑 `claude_desktop_config.json` |
| **Claude Code CLI** | 在终端中运行 `claude mcp add-json` 命令 |
### 截图
<p align="center">
<img src="assets/1-configure-credentials.png" alt="配置凭证" width="600"/>
</p>
<p align="center">
<text>输入您的 Zotero 凭证。您可以在 Zotero 账户设置中找到您的库 ID 和 API 密钥。点击“部署”并按照说明将远程 MCP 服务器添加到 Claude Desktop。</text>
</p>
<p align="center">
<img src="assets/2-connection-to-claude-instructions.png" alt="连接到 Claude 说明" width="600"/>
</p>
<p align="center">
<text>按照说明连接到 Claude Desktop。</text>
</p>
<p align="center">
<img src="assets/3-claude-desktop-configuration.png" alt="Claude Desktop 配置" width="600"/>
</p>
<p align="center">
<text>
将远程 MCP 服务器添加到 Claude Desktop。您可以在部署后在设置向导中找到您的 MCP URL。
</text>
</p>
### 可选设置
<p align="center">
<img src="assets/4-configure-mcp-server-settings.png" alt="配置 MCP 服务器设置" width="600"/>
<img src="assets/5-turn-on-always-allow.png" alt="启用始终允许" width="600"/>
</p>
<p align="center">
<text>启用“始终允许”以避免每次请求都需要批准。</text>
</p>
## 手动设置（高级）
如果您更喜欢自己配置所有内容而无需设置向导，或者想在本地开发。首先按照 [快速开始](#快速开始) 中的方法克隆和安装。
### 1. 配置本地开发凭证
创建一个包含您的 Zotero 凭证的 `.dev.vars` 文件：
```
ZOTERO_API_KEY=您的-api-key-此处
ZOTERO_LIBRARY_ID=您的-library-id-此处
BEARER_TOKEN=任何-local-dev-的-secret-token
```
### 2. 在本地运行
```sh
npm run dev
```
服务器启动在 `http://localhost:8787/mcp`。
### 3. 部署到 Cloudflare
```sh
# 登录到 Cloudflare（如果尚未登录）
npx wrangler login
# 部署 Worker
npm run deploy
# 设置生产机密
npx wrangler secret put ZOTERO_API_KEY
npx wrangler secret put ZOTERO_LIBRARY_ID
npx wrangler secret put BEARER_TOKEN
```
### 4. 从 Claude 连接
**选项 A：Claude Desktop UI（推荐）**
使用 URL 中的 token 格式，以便您可以粘贴单个 URL 而无需高级设置：
```
https://zotero-assistant-mcp.<您的子域名>.workers.dev/mcp/t/<您的-bearer-token>
```
1. 打开 Claude Desktop → 设置 → 连接器
2. 点击“添加自定义连接器”
3. 将名称设置为 **Zotero 助手**
4. 粘贴上述 URL
5. 点击“添加”
**选项 B：JSON 配置**
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）：
```json
{
"mcpServers": {
"zotero": {
"command": "npx",
"args": [
"mcp-remote",
"https://zotero-assistant-mcp.<您的子域名>.workers.dev/mcp",
"--header",
"Authorization:${AUTH_HEADER}"
],
"env": {
"AUTH_HEADER": "Bearer <您的-bearer-token>"
}
}
}
}
```
**选项 C：Claude Code CLI**
```sh
claude mcp add-json zotero '{"type":"http","url":"https://zotero-assistant-mcp.<您的子域名>.workers.dev/mcp","headers":{"Authorization":"Bearer <您的-bearer-token>"}}'
```
## 本地服务器（替代）
如果您不想部署到 Cloudflare，您可以在本地作为 stdio 子进程运行 MCP 服务器。无需云账户 — 只需您的 Zotero 凭证。
### Claude Desktop 配置
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"zotero": {
"command": "npx",
"args": ["zotero-assistant-mcp"],
"env": {
"ZOTERO_API_KEY": "您的-api-key-此处",
"ZOTERO_LIBRARY_ID": "您的-library-id-此处"
}
}
}
}
```
### Claude Code CLI
```sh
claude mcp add zotero -- npx zotero-assistant-mcp \
--env ZOTERO_API_KEY=您的-api-key \
--env ZOTERO_LIBRARY_ID=您的-library-id
```
### 获取您的凭证
1. 前往 [zotero.org/settings/keys](https://www.zotero.org/settings/keys)
2. 创建具有读写权限的新 API 密钥
3. 您的库 ID 显示在同一页面上（它是您个人资料 URL 中的数字）
## 作为库使用
`zotero-assistant-mcp` 包可以被其他项目导入以构建自定义集成：
```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { registerTools } from "zotero-assistant-mcp";
const server = new McpServer({ name: "my-server", version: "1.0.0" });
registerTools(server, { apiKey: "...", libraryId: "..." });
// 连接到您想要的任何传输
```
Zotero API 函数也单独导出：
```typescript
import { searchItems, createItem, getItem } from "zotero-assistant-mcp";
const results = await searchItems(apiKey, libraryId, { query: "机器学习" });
```
## 安全
每个 MCP 端点都受 bearer token 保护。服务器支持两种身份验证方法：
1. **URL 路径中的 token** — `/mcp/t/{token}`（适用于 Claude Desktop 的连接器 UI）
2. **Bearer 头** — `Authorization: Bearer {token}`（适用于 API/CLI 使用的标准 HTTP 身份验证）
未经身份验证的 `/mcp` 请求返回 `401 Unauthorized`。
您的 Zotero API 密钥和 bearer token 存储为 [Cloudflare Worker 机密](https://developers.cloudflare.com/workers/configuration/secrets/) — 它们在存储和日志或源代码中都经过加密。
> **请保持您的 MCP URL 和 bearer token 私密。** 任何拥有该 token 的人都可以读写您的 Zotero 库。
## Cloudflare 账户常见问题
**我需要付费的 Cloudflare 计划吗？**
不。 [Workers 免费计划](https://developers.cloudflare.com/workers/platform/pricing/) 包括每天 100,000 次请求 — 足以满足个人 MCP 使用需求。无需信用卡即可注册。
**设置向导如何检测我的 Cloudflare 账户？**
向导在后台运行 `wrangler whoami`，它会检查本地存储的 OAuth token 是否来自以前的 `wrangler login`。这是 Wrangler CLI 使用的相同机制 — 设置向导不会存储任何密码。
**如果我没有 Cloudflare 账户怎么办？**
向导将在步骤 3 中显示“未登录”状态。点击“登录到 Cloudflare” — 这将运行 `wrangler login`，它将在您的浏览器中打开 Cloudflare 网站。从那里，您可以登录或创建免费账户。一旦身份验证，向导将自动检测您的登录并继续部署。
**我可以使用 GitHub/Google 登录吗？**
是的。Cloudflare 支持电子邮件、Google 和 Apple 登录。当 `wrangler login` 打开您的浏览器时，您可以使用这些方法创建或访问您的账户。
## 可用工具（18）
| 类别 | 工具 | 描述 |
|----------|------|-------------|
| 实用程序 | `get_help` | 工作流程说明 |
| 实用程序 | `get_item_types` | 列出有效的项目类型 |
| 实用程序 | `prepare_url` | 获取 URL 的获取说明 |
| 搜索 | `search_items` | 按文本、标签、类型或集合搜索 |
| 搜索 | `get_collection_items` | 列出集合中的项目 |
| 搜索 | `get_recent_items` | 最近添加/修改的项目 |
| 搜索 | `list_collections` | 所有集合（文件夹） |
| 搜索 | `create_collection` | 创建新集合 |
| 搜索 | `list_tags` | 库中的所有标签 |
| 读取 | `get_item` | 项目的完整元数据 + 子项 |
| 读取 | `get_item_fulltext` | 提取的文本内容 |
| 读取 | `get_attachment_content` | 读取快照 HTML 或附件文件 |
| 读取 | `get_library_stats` | 库概览，包含计数和热门标签 |
| 写入 | `save_item` | 创建具有元数据的新项目 |
| 写入 | `attach_pdf` | 将 PDF 附加到现有项目 |
| 写入 | `attach_snapshot` | 附加网页快照 |
| 写入 | `create_note` | 在现有项目上创建注释 |
| 写入 | `update_item` | 修改元数据/标签 |
## 项目结构
```
packages/
├── mcp/ # zotero-assistant-mcp — 纯 MCP 库 + stdio CLI
│ ├── src/
│ │ ├── index.ts # registerTools() + 重新导出
│ │ └── zotero.ts # Zotero API 包装器
│ ├── bin/cli.ts # npx zotero-assistant-mcp
│ └── tests/
└── deploy/ # Cloudflare Workers 部署程序
├── src/
│ └── index.ts # Worker 入口（McpAgent + 身份验证）
├── setup/ # 基于浏览器的设置向导（npm run setup）
└── wrangler.jsonc
```
## 使用 MCP Inspector 进行测试
```sh
npm run dev # 在一个终端中
# 在另一个终端中：
npx @modelcontextprotocol/inspector@latest
```
打开 `http://localhost:5173` 并连接到 `http://localhost:8787/mcp`。
## 许可证
MIT
