195 lines
6.7 KiB
Markdown
195 lines
6.7 KiB
Markdown
# MCP 服务配置指南
|
||
|
||
Claude Scholar 依赖 MCP（Model Context Protocol）服务器提供扩展能力。MCP 服务器**不包含**在本仓库中，用户需自行安装和配置。
|
||
|
||
## 所需 MCP 服务
|
||
|
||
### 1. Zotero MCP（研究工作流）
|
||
|
||
**使用场景**: `literature-reviewer` agent、`/research-init`、`/zotero-review`、`/zotero-notes` 命令
|
||
|
||
**安装包**: [Galaxy-Dawn/zotero-mcp](https://github.com/Galaxy-Dawn/zotero-mcp) — 可自动识别本地 Zotero desktop 与 Web API 模式；只有远程访问或写操作时才需要 Web 凭证。
|
||
|
||
#### 功能
|
||
|
||
| 类别 | 工具 |
|
||
|------|------|
|
||
| **导入** | `zotero_add_items_by_identifier`, `zotero_add_items_by_doi`, `zotero_add_items_by_arxiv`, `zotero_add_item_by_url` |
|
||
| **读取** | `zotero_get_collections`, `zotero_get_collection_items`, `zotero_search_items`, `zotero_semantic_search` |
|
||
| **更新** | `zotero_update_item`, `zotero_update_note`, `zotero_create_collection`, `zotero_move_items_to_collection`, `zotero_reconcile_collection_duplicates` |
|
||
| **删除** | `zotero_delete_items`（移至回收站）, `zotero_delete_collection` |
|
||
| **PDF** | `zotero_find_and_attach_pdfs`（基于来源感知的 PDF cascade）, `zotero_add_linked_url_attachment` |
|
||
|
||
#### 前置条件
|
||
|
||
1. 如果你希望在没有 Web API 凭证的情况下使用本地只读能力，请安装 [Zotero](https://www.zotero.org/)
|
||
2. 如果你要使用写操作或远程 Web API，请打开 [Zotero 设置 -> Security -> Applications](https://www.zotero.org/settings/security#applications)
|
||
3. 点击 `Create new private key` 生成 API key
|
||
4. 在同一页面按钮下方可以看到 `User ID`，个人库场景下这个数字就是 `ZOTERO_LIBRARY_ID`
|
||
|
||
#### 安装
|
||
|
||
```bash
|
||
# 通过 uv 安装（推荐）
|
||
uv tool install git+https://github.com/Galaxy-Dawn/zotero-mcp.git
|
||
```
|
||
|
||
#### 配置
|
||
|
||
选择您的平台：
|
||
|
||
##### Claude Code
|
||
|
||
Claude Code v2.1.5+：在 `~/.claude.json` 的 `mcpServers` 中添加。
|
||
|
||
更早版本：在 `~/.claude/settings.json` 的 `mcpServers` 中添加：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"zotero": {
|
||
"command": "zotero-mcp",
|
||
"args": ["serve"],
|
||
"env": {
|
||
"ZOTERO_API_KEY": "your-api-key",
|
||
"ZOTERO_LIBRARY_ID": "your-user-id",
|
||
"ZOTERO_LIBRARY_TYPE": "user",
|
||
"UNPAYWALL_EMAIL": "your-email@example.com",
|
||
"UNSAFE_OPERATIONS": "all"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
##### Codex CLI
|
||
|
||
在 `~/.codex/config.toml` 中添加：
|
||
|
||
```toml
|
||
[mcp_servers.zotero]
|
||
command = "zotero-mcp"
|
||
args = ["serve"]
|
||
enabled = true
|
||
|
||
[mcp_servers.zotero.env]
|
||
ZOTERO_API_KEY = "your-api-key"
|
||
ZOTERO_LIBRARY_ID = "your-user-id"
|
||
ZOTERO_LIBRARY_TYPE = "user"
|
||
UNPAYWALL_EMAIL = "your-email@example.com"
|
||
UNSAFE_OPERATIONS = "all"
|
||
NO_PROXY = "localhost,127.0.0.1"
|
||
```
|
||
|
||
##### OpenCode
|
||
|
||
在 `~/.opencode/opencode.jsonc` 中添加：
|
||
|
||
```jsonc
|
||
{
|
||
"mcp": {
|
||
"zotero": {
|
||
"type": "local",
|
||
"command": ["zotero-mcp", "serve"],
|
||
"enabled": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
然后在 `~/.zshrc` 中设置环境变量：
|
||
|
||
```bash
|
||
# Zotero MCP
|
||
export ZOTERO_API_KEY="your-api-key"
|
||
export ZOTERO_LIBRARY_ID="your-user-id"
|
||
export ZOTERO_LIBRARY_TYPE="user"
|
||
export UNPAYWALL_EMAIL="your-email@example.com"
|
||
export UNSAFE_OPERATIONS="all"
|
||
```
|
||
|
||
#### 环境变量
|
||
|
||
| 变量 | 必需 | 说明 |
|
||
|------|------|------|
|
||
| `ZOTERO_API_KEY` | 本地只读可不填；Web/写操作必填 | 您的 Zotero API 密钥 |
|
||
| `ZOTERO_LIBRARY_ID` | 本地只读可不填；Web/写操作必填 | 个人库场景下填写 Zotero 页面显示的 `User ID`（数字） |
|
||
| `ZOTERO_LIBRARY_TYPE` | 是 | `user` 或 `group` |
|
||
| `UNPAYWALL_EMAIL` | 否 | 用于 Unpaywall PDF 搜索的邮箱 |
|
||
| `UNSAFE_OPERATIONS` | 否 | `items`（delete_items）, `all`（delete_collection） |
|
||
| `NO_PROXY` | 否 | 绕过本地代理 |
|
||
|
||
说明：
|
||
- 最小本地配置只需要 `command = "zotero-mcp"` 和 `args = ["serve"]`。
|
||
- 不要把 `your-api-key`、`your-user-id`、`your-email@example.com` 这类占位符直接保留在正式配置里。
|
||
|
||
#### 可用工具
|
||
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| `zotero_get_collections` | 列出所有集合 |
|
||
| `zotero_get_collection_items` | 获取集合中的条目 |
|
||
| `zotero_search_items` | 按关键词搜索库 |
|
||
| `zotero_search_by_tag` | 按标签搜索 |
|
||
| `zotero_get_item_metadata` | 获取条目元数据和摘要 |
|
||
| `zotero_get_item_fulltext` | 读取 PDF 全文 |
|
||
| `zotero_get_annotations` | 获取 PDF 标注 |
|
||
| `zotero_get_notes` | 获取笔记 |
|
||
| `zotero_semantic_search` | 语义搜索（使用嵌入向量） |
|
||
| `zotero_advanced_search` | 高级搜索 |
|
||
| `zotero_add_items_by_identifier` | 通过 DOI、arXiv、落地页或直链 PDF 智能导入论文；若 Web 上传撞到存储配额且本地 Zotero Desktop 正在运行，可回退为本地 connector copy（`pdf_source=local_zotero_copy`），或复用已有本地副本（`pdf_source=local_zotero_existing_copy`），并在可用时返回 `local_item_key=...` |
|
||
| `zotero_add_items_by_doi` | 通过 DOI 导入论文 |
|
||
| `zotero_add_items_by_arxiv` | 通过 arXiv ID 导入预印本 |
|
||
| `zotero_add_item_by_url` | 将网页保存为条目 |
|
||
| `zotero_update_item` | 更新条目字段 |
|
||
| `zotero_update_note` | 更新笔记内容 |
|
||
| `zotero_create_collection` | 创建集合 |
|
||
| `zotero_move_items_to_collection` | 在集合间移动条目 |
|
||
| `zotero_update_collection` | 重命名集合 |
|
||
| `zotero_delete_collection` | 删除集合 |
|
||
| `zotero_delete_items` | 将条目移至回收站 |
|
||
| `zotero_find_and_attach_pdfs` | 为已有条目重新运行来源感知 PDF cascade |
|
||
| `zotero_reconcile_collection_duplicates` | 导入后的去重与 collection 级清理 |
|
||
| `zotero_add_linked_url_attachment` | 添加链接 URL 附件 |
|
||
|
||
工作流说明：Claude Scholar 当前默认使用 `zotero_add_items_by_identifier` 做论文导入，并使用 `zotero_reconcile_collection_duplicates` 作为标准导入后清理步骤。import ledger 与 local-copy reconcile 属于内部诊断能力，不是默认公开 MCP tools。
|
||
|
||
### 2. 浏览器自动化 MCP（可选）
|
||
|
||
用途: Chrome 浏览器控制、网页交互。
|
||
|
||
#### 配置
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"streamable-mcp-server": {
|
||
"type": "streamable-http",
|
||
"url": "http://127.0.0.1:12306/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 验证
|
||
|
||
配置完成后，重启您的 CLI 并验证 MCP 服务是否连接：
|
||
|
||
```
|
||
# Zotero 示例：
|
||
> 列出我的 Zotero 集合
|
||
|
||
```
|
||
|
||
如果工具返回了数据（如集合列表），说明配置成功。
|
||
|
||
## 常见问题
|
||
|
||
| 问题 | 解决方案 |
|
||
|------|---------|
|
||
| 工具返回错误 | 检查 API 密钥和库 ID 是否正确 |
|
||
| PDF 附加失败 | 确保已设置 `UNPAYWALL_EMAIL` |
|
||
| 删除操作被阻止 | 设置 `UNSAFE_OPERATIONS=items` 或 `all` |
|
||
| HTTP 错误 | 检查 `NO_PROXY` 是否包含 localhost |
|
||
| API 速率限制 (429) | 每批 ≤10 篇论文，批次间添加延迟 |
|