mcp-server-zotero-dev

Zotero 插件开发 MCP 服务

一个 MCP（模型上下文协议） 服务，可帮助 AI 助手构建、测试和调试 Zotero 7+ 插件。它提供 25 种工具，用于 UI 检查、JavaScript 执行、构建集成、日志记录、数据库访问和插件管理。

工作原理：Zotero 7+ 基于 Firefox ESR 构建，因此此服务通过 Firefox 内置的远程调试协议（RDP）与 Zotero 通信。一个小型配套插件（MCP Bridge for Zotero）会在 Zotero 中启动 DevTools 服务，而此 MCP 服务连接到该服务。

AI Assistant (Claude, Cursor, Windsurf, etc.)
         | MCP Protocol (stdio)
         v
    MCP Server (this package)
         | Firefox RDP (TCP port 6100)
         v
    Zotero + MCP Bridge Plugin

前置条件

• Node.js >= 20
• Zotero 7+（正式版、测试版或开发版）
• 在 Zotero 中安装 MCP Bridge for Zotero 插件 — 下载最新的 XPI

安装 MCP Bridge 插件

1. 从 GitHub Releases 下载 zotero-mcp-bridge-*.xpi
2. 在 Zotero 中：工具 > 附加组件 > 齿轮图标 > 从文件安装附加组件...
3. 选择下载的 .xpi 文件
4. 重启 Zotero

Zotero 启动时，插件会自动在端口 6100 上启动 DevTools 服务。

设置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "zotero-dev": {
      "command": "npx",
      "args": ["-y", "@introfini/mcp-server-zotero-dev"]
    }
  }
}

Claude Code

claude mcp add zotero-dev -- npx -y @introfini/mcp-server-zotero-dev

Cursor / Windsurf / 其他 MCP 客户端

使用以下配置设置 MCP 服务：

• 命令：npx
• 参数：-y @introfini/mcp-server-zotero-dev

或者全局安装：

npm install -g @introfini/mcp-server-zotero-dev

工具（25 种）

JavaScript 执行与检查

工具	描述
zotero_ping	测试与 Zotero 的连接并获取版本信息
zotero_execute_js	在 Zotero 的特权 chrome 上下文中执行 JavaScript
zotero_get_pref	获取 Zotero 首选项的值
zotero_set_pref	设置 Zotero 首选项的值
zotero_search_prefs	搜索并列出 Zotero/Firefox 首选项
zotero_inspect_object	检查 JavaScript 对象以发现其方法和属性
zotero_open_preferences	打开 Zotero 的首选项窗口，可选择跳转到某个面板

UI 检查

工具	描述
zotero_screenshot	截取 Zotero 的屏幕截图（主窗口、指定窗口或元素）
zotero_inspect_element	根据 CSS 选择器查找 DOM 元素
zotero_get_dom_tree	获取简化的 DOM 树结构
zotero_get_styles	获取元素的计算后 CSS 样式
zotero_list_windows	列出所有已打开的 Zotero 窗口

日志与调试

工具	描述
zotero_read_logs	读取 Zotero 的调试日志输出
zotero_read_errors	读取 Zotero 错误控制台中的错误
zotero_clear_logs	清除调试日志缓冲区和错误控制台
zotero_watch_logs	开始/停止监视新日志消息

构建集成

工具	描述
zotero_scaffold_build	使用 zotero-plugin-scaffold 构建 Zotero 插件
zotero_scaffold_serve	启动/停止支持热重载的开发服务器
zotero_scaffold_lint	在插件项目上运行 ESLint
zotero_scaffold_typecheck	运行 TypeScript 类型检查

插件管理

工具	描述
zotero_plugin_reload	重新加载 Zotero 插件
zotero_plugin_list	列出所有已安装的插件
zotero_plugin_install	从本地 XPI 文件安装插件

数据库访问（只读）

工具	描述
zotero_db_query	在 Zotero 数据库上执行 SELECT 查询
zotero_db_schema	获取数据库架构信息
zotero_db_stats	获取数据库统计信息

提示词（5）

提示词	描述
setup-dev	从头搭建 Zotero 插件开发环境
debug-plugin	连接到 Zotero 并开始调试插件
fix-errors	查找并修复 Zotero 错误控制台中的错误
inspect-api	交互式探索 Zotero 的 JavaScript API
migrate-z7	帮助将插件从 Zotero 6 迁移到 Zotero 7

配置

环境变量（均为可选）：

变量	默认值	描述
ZOTERO_RDP_PORT	6100	要连接的 RDP 端口
ZOTERO_RDP_HOST	localhost	RDP 主机地址
ZOTERO_DATA_DIR	自动检测	Zotero 数据目录路径
ZOTERO_PROFILE_PATH	自动检测	Zotero 配置文件路径

故障排除

“无法连接到 Zotero”

1. 确保 Zotero 正在运行
2. 确认 MCP Bridge 插件已安装（工具 > 附加组件）
3. 安装插件后重启 Zotero
4. 检查端口 6100 是否被阻止：lsof -i :6100

“端口已被占用”

• 可能有另一个 Zotero 实例正在运行，或者 Zotero 是通过 -debugger 标志启动的（该标志使用端口 6000）。MCP Bridge 使用端口 6100，以避免冲突。

许可证

MIT