内容
# zotero-mcp-server-write
一个模型上下文协议（MCP）服务器，暴露本地Zotero安装的*写入*操作给LLM代理。它是一个薄的异步包装器，围绕着配套的[`zotero_write_api_plugin`](https://github.com/akchan/zotero_write_api_plugin) Zotero插件，该插件在`http://127.0.0.1:23119`上为Zotero的内置本地服务器添加了HTTP端点。它们一起允许代理通过DOI导入项目，使用Zotero的元数据识别器读取PDF，将文件附加到现有项目，并添加格式化笔记。
## 前提条件
您必须在Zotero中安装 **`zotero_write_api_plugin`** XPI，然后此MCP服务器才能执行任何有用的操作。从 [github.com/akchan/zotero_write_api_plugin/releases](https://github.com/akchan/zotero_write_api_plugin/releases) 下载最新版本，并通过Zotero中的 *工具 → 附加组件 → 从文件安装附加组件...* 进行安装。确保在您使用MCP服务器时，Zotero正在运行。
## 推荐配对
该服务器仅涵盖*写入*操作。对于*读取*操作（搜索库、浏览收藏、获取项目元数据、获取标签等），请在[`54yyyu/zotero-mcp`](https://github.com/54yyyu/zotero-mcp)旁边安装它。两者一起为代理提供了一个完整的视图和编辑本地Zotero库的界面。此服务器中的工具描述明确指出`54yyyu/zotero-mcp`是发现`item_key`和`collection_key`值的方法。
## 安装/运行
该服务器已在PyPI上发布为`zotero-mcp-server-write`：
```bash
# 按需使用uv运行（推荐；匹配下面的Claude Desktop配置）
uvx zotero-mcp-server-write
# 或使用pip安装到虚拟环境/全局
pip install zotero-mcp-server-write
zotero-mcp-server-write
```
控制台脚本入口点与包名相同。
## 工具
| 工具 | 描述 |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| `add_by_doi` | 从DOI / ISBN / arXiv ID / PMID（自动检测类型）导入新项目。 |
| `add_pdf` | 导入本地PDF，然后运行Zotero的元数据识别器以查找父项目。 |
| `attach_pdf_to_item` | 将本地文件（通常是PDF）附加到现有Zotero项目，方法是通过`item_key`。 |
| `add_note` | 向现有项目添加子笔记。接受markdown（渲染为HTML）或原始HTML。 |
| `update_note` | 替换现有笔记项目的正文（markdown或原始HTML）。 |
| `add_tags` | 向现有项目添加一个或多个标签。已经存在的标签将被跳过，不会报错。 |
## Claude Desktop 配置示例
在Claude Desktop中注册读写服务器：
```json
{
"mcpServers": {
"zotero-mcp": {
"command": "uvx",
"args": ["zotero-mcp"]
},
"zotero-mcp-server-write": {
"command": "uvx",
"args": ["zotero-mcp-server-write"],
"env": {
"ZOTERO_LOCAL_API_BASE": "http://127.0.0.1:23119",
"ZOTERO_WRITE_TIMEOUT": "60"
}
}
}
}
```
## 环境变量
| 变量 | 默认值 | 目的 |
| ------------------------ | -------------------------- | ------------------------------------------------------------------ |
| `ZOTERO_LOCAL_API_BASE` | `http://127.0.0.1:23119` | Zotero本地HTTP服务器的基准URL（插件插入的位置）。 |
| `ZOTERO_WRITE_TIMEOUT` | `60`（秒） | 插件端点的每个请求的HTTP超时。 |
## 不在范围内
- **组库。** 仅针对用户的本地库；组库写入不支持底层插件。
- **收藏管理。** 此服务器不创建、重命名、删除或重新分配收藏。标签*添加*通过`add_tags`支持，但重命名/删除标签不支持。请使用[`54yyyu/zotero-mcp`](https://github.com/54yyyu/zotero-mcp)进行读取访问这些结构，并在需要时在Zotero UI中编辑它们。
## 许可证
MIT，见 [LICENSE](LICENSE)。
