🚀 Zotero 的 Model Context Protocol (MCP) 服务器
本项目是一个基于 Python 的服务器，实现了 Model Context Protocol (MCP) 与 Zotero 的集成，借助该服务器，您能够通过 AI 助手访问 Zotero 文献库。项目致力于实现一组功能虽小但尽可能实用的交互操作，以便与 MCP 客户端 进行通信。
🚀 快速开始
本项目实现了 MCP 与 Zotero 的集成，让您可以利用 AI 助手便捷访问 Zotero 文献库。下面将为您介绍项目的功能、安装方式以及开发相关信息。
✨ 主要特性
此 MCP 服务器提供了以下实用工具：
zotero_search_items：可使用文本查询在您的 Zotero 文献库中搜索项目。zotero_item_metadata：用于获取特定 Zotero 项目的详细元数据信息。zotero_item_fulltext：能够获取特定 Zotero 项目的全文内容（例如 PDF 文件）。
这些工具可通过任何 MCP 客户端或 MCP Inspector 发现和访问。每个工具都会返回包含相关 Zotero 项目信息的格式化文本，AI 助手（如 Claude）可以按顺序使用它们，先搜索项目再获取其元数据或全文内容。
📦 安装指南
此服务器可以与 Zotero 的本地 API 或远程 Web API 通信，以下为您介绍两种安装方式：
方式一：使用 Docker 容器
在 mcp.json 文件中添加以下配置，将占位符替换为您的实际 API 密钥和文献库 ID：
{
"mcpServers": {
"zotero": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "ZOTERO_API_KEY=PLACEHOLDER", // 替换为您的 API 密钥
"-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER", // 替换为您的文献库 ID
"ghcr.io/kujenga/zotero-mcp:main"
]
}
}
}
方式二：本地安装
- 克隆此仓库。
- 使用 uv 安装依赖项，运行命令：
uv sync
- 在项目根目录创建一个
.env文件，包含以下环境变量：
# 使用本地 API 时
ZOTERO_API=local
# 或使用远程 Web API 时
ZOTERO_API_KEY=your_api_key_here
ZOTERO_LIBRARY_ID=your_library_id_here
🔧 技术细节
开发信息
若要进行开发或贡献代码，请按以下步骤操作：
- 克隆此仓库。
- 使用 uv 安装依赖项，运行命令：
uv sync
- 在项目根目录创建一个
.env文件，包含所需的环境变量。
启动 MCP Inspector 进行本地开发：
npx @modelcontextprotocol/inspector uv run zotero-mcp
若要测试与 Claude Desktop 的集成，请在您的 Claude 配置中添加以下内容，将 /path/to 替换为实际路径：
{
"mcpServers": {
"zotero": {
"command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp",
"env": {
// 添加所需的环境变量配置
}
}
}
}
运行测试
要运行测试套件，请运行命令：
uv run pytest
Docker 开发
使用以下命令构建容器镜像：
docker build . -t zotero-mcp:local
要通过 Inspector 测试容器，请运行命令：
npx @modelcontextprotocol/inspector \
-e ZOTERO_API_KEY=$ZOTERO_API_KEY \
-e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
docker run --rm -i \
--env ZOTERO_API_KEY \
--env ZOTERO_LIBRARY_ID \
zotero-mcp:local
📚 详细文档
以下是一些相关文档链接，供您参考：
- https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
- https://github.com/modelcontextprotocol/python-sdk
- https://pyzotero.readthedocs.io/en/latest/
- https://www.zotero.org/support/dev/web_api/v3/start