使用说明

项目简介

Zotero MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在将 Zotero 文献管理软件的功能集成到支持 MCP 协议的 AI 应用中。通过该服务器，AI 应用可以方便地访问和操作 Zotero 图书馆中的文献资源，例如搜索文献、获取引用、添加条目等，从而增强 AI 应用的上下文感知能力和知识管理能力。

主要功能点

文献检索: 允许 AI 应用通过关键词在 Zotero 图书馆中搜索文献条目。
获取引用: 支持为指定文献条目生成多种格式的引用信息，方便在 AI 应用中引用文献。
添加条目: 允许 AI 应用向 Zotero 图书馆添加新的文献条目，扩展知识库。
访问馆藏: 提供对 Zotero 馆藏的结构化访问，包括集合（collections）和条目（items）列表。
支持个人和群组图书馆: 可以配置连接到个人 Zotero 图书馆或群组图书馆。

安装步骤

克隆仓库:

git clone https://github.com/cr625/zotero-mcp-server.git
cd zotero-mcp-server

创建并激活虚拟环境 (推荐):

python -m venv venv
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate  # Windows

安装依赖:

pip install -r requirements.txt

服务器配置

MCP 客户端需要配置服务器的启动命令才能连接 Zotero MCP Server。以下是配置信息，请复制到您的 MCP 客户端的服务器配置中。

{
  "server_name": "zotero-mcp-server",
  "command": "python",
  "args": ["src/server.py"],
  "description": "Zotero MCP Server for accessing and managing Zotero libraries."
}

参数注释:

'server_name': 服务器的名称，可以自定义，用于在 MCP 客户端中标识该服务器。
'command': 启动服务器的命令，这里使用 'python' 解释器。
'args': 传递给 'python' 命令的参数，'["src/server.py"]' 指定了服务器脚本的路径。
'description': 服务器的简要描述，方便用户理解服务器的功能。

Zotero API 密钥配置:

Zotero MCP Server 需要 Zotero API 密钥才能访问您的 Zotero 图书馆。请按照以下步骤配置 API 密钥：

复制 '.env.example' 文件为 '.env':

cp .env.example .env

编辑 '.env' 文件，填入您的 Zotero API 密钥和用户 ID (或群组 ID):

ZOTERO_API_KEY=您的_Zotero_API_密钥
ZOTERO_USER_ID=您的_Zotero_用户ID  # 个人图书馆
# ZOTERO_GROUP_ID=您的_Zotero_群组ID # 群组图书馆，如果使用群组图书馆则取消注释

您需要访问 Zotero settings/keys 获取 API 密钥。
用户 ID 和群组 ID 可以在 Zotero 网站 URL 中找到，或者运行仓库提供的 'find_zotero_id.py' 脚本获取。

基本使用方法

启动服务器: 在终端中，激活虚拟环境（如果已创建），并运行以下命令启动 Zotero MCP Server：
```
python src/server.py
```
服务器将监听标准输入/输出 (stdio) 上的 JSON-RPC 请求。
使用 MCP 客户端连接: 配置您的 MCP 客户端，使其连接到使用命令 'python src/server.py' 启动的服务器。客户端将通过 JSON-RPC 协议与服务器通信，发送请求并接收响应。
测试服务器 (可选): 您可以运行仓库提供的 'simple_test.py' 或 'test_client.py' 脚本来测试服务器的基本功能是否正常。

资源 (Resources)

'zotero://collections': 获取 Zotero 图书馆中的所有集合列表。
'zotero://items/top': 获取 Zotero 图书馆中的顶层条目列表。
'zotero://items/recent': 获取最近在 Zotero 图书馆中添加或修改的条目列表。
'zotero://collections/{collection_key}/items': 获取指定集合中的条目列表，需要替换 '{collection_key}' 为实际的集合键值。
'zotero://items/{item_key}': 获取指定条目的详细信息，需要替换 '{item_key}' 为实际的条目键值。
'zotero://items/{item_key}/citation/{style}': 获取指定条目的引用，可以指定引用样式 (如 apa, mla, chicago)，需要替换 '{item_key}' 和 '{style}'。

工具 (Tools)

'search_items': 在 Zotero 图书馆中搜索条目。
- 参数:
  - 'query' (string, 必需): 搜索关键词。
  - 'collection_key' (string, 可选): 指定在哪个集合中搜索。
  - 'limit' (number, 可选): 限制返回结果的数量，默认为 20。
'get_citation': 获取指定条目的引用。
- 参数:
  - 'item_key' (string, 必需): 条目键值。
  - 'style' (string, 可选): 引用样式，默认为 "apa"。
'add_item': 向 Zotero 图书馆添加新条目。
- 参数:
  - 'item_type' (string, 必需): 条目类型 (如 journalArticle, book, webpage)。
  - 'title' (string, 必需): 条目标题。
  - 'creators' (array, 可选): 作者或创建者信息，包含 'creatorType', 'firstName', 'lastName' 字段。
  - 'collection_key' (string, 可选): 指定添加到哪个集合。
  - 'additional_fields' (object, 可选): 其他字段，根据条目类型不同而不同。
'get_bibliography': 获取多个条目的 bibliography。
- 参数:
  - 'item_keys' (array, 必需): 条目键值数组。
  - 'style' (string, 可选): 引用样式，默认为 "apa"。

关键词