zotero-word-mcp

zotero-word-mcp 是一个面向 Windows 的 MCP Server，用于把 Zotero 原生动态引文 直接插入 Microsoft Word 桌面版 文档。

它不是静态编号脚本，也不是通用 .docx 编辑器，而是专门解决下面这个断点：

• Zotero MCP 负责文献库
• Word MCP 负责文档内容
• 但 AI 很难把 Zotero 可继续维护的原生引文 真正插进 Word

本项目补上的就是这一步。

核心能力

• 向 Word 文档插入 Zotero 原生 ADDIN ZOTERO_ITEM 引文字段
• 向 Word 文档插入 Zotero 原生 ADDIN ZOTERO_BIBL 参考文献字段
• 写入 ZOTERO_PREF_1..N 文档首选项
• 触发 Zotero 官方 Word Refresh
• 列出文档中的 Zotero 原生字段
• 设置文档的 CSL 样式
• 使用 Zotero 官方 libzoteroWinWordIntegration.dll 探测文档是否可被识别

为什么单独做这个 MCP

普通 Word MCP 更适合：

• 插段落
• 排版
• 查找替换
• 表格/图片处理

而 zotero-word-mcp 解决的是：

• 引文必须是 Zotero 原生字段
• 刷新后要继续被 Zotero 插件接管
• 用户后续还要能在 Word 里继续点 Add/Edit Citation

这决定了它必须直接面向 Zotero Word 集成，而不是只写普通文本。

适用环境

• Windows
• Microsoft Word 桌面版
• Zotero 7
• Python 3.10+

当前未完整验证：

• WPS
• Word Online
• 受保护文档
• 多人实时协作文档

安装

git clone https://github.com/Zhangchaokai1/zotero-word-mcp.git
cd zotero-word-mcp
pip install -e .

如果你只想本地运行：

pip install "mcp[cli]" pywin32 requests

配置

可选环境变量：

• ZOTERO_DATA_DIR Zotero 数据目录，例如 D:\Zotero\ZoteroFile
• ZOTERO_SQLITE_PATH 指向 zotero.sqlite
• ZOTERO_WORD_DLL 指向 libzoteroWinWordIntegration.dll

如果不显式设置，程序会优先从 Zotero prefs.js 自动发现数据目录。

MCP 工具

insert_citation

向 Word 文档插入 Zotero 原生引文。

主要参数：

• doc
• keys
• find_text
• placement
• style_id
• library_id
• prefix
• suffix
• refresh_after
• wait_seconds

insert_bibliography

向 Word 文档插入 Zotero 原生参考文献字段。

refresh_document

触发 Zotero 官方 Refresh，并等待占位字段解析完成。

list_fields

列出文档中的 Zotero 原生字段和文档首选项。

set_document_style

设置文档 Zotero CSL 样式，不立即刷新。

probe_document

调用 Zotero 官方 libzoteroWinWordIntegration.dll 验证当前文档是否能被官方集成识别。

启动服务

zotero-word-mcp

如果你的 MCP 客户端支持命令式 server，可以这样配置：

[mcp_servers.zotero-word]
command = "python"
args = ["-m", "zotero_word_mcp"]

项目结构

• src/zotero_word_mcp/word_bridge.py Word COM 基础桥接
• src/zotero_word_mcp/native_bridge.py Zotero 原生字段与刷新逻辑
• src/zotero_word_mcp/server.py MCP 工具封装
• docs/DEVELOPMENT_REVIEW.md 开发复盘与技术路线说明

与静态引用方案的区别

静态方案通常是：

• 正文写 [1]
• 文末写普通文本参考文献
• 再靠 Word 交叉引用或脚本刷新

这类方案容易控，但不是 Zotero 原生动态引文。

本项目写入的是 Zotero 官方 Word 集成可识别的字段，因此：

• Zotero 可以继续接管这份文档
• 用户后续仍能用 Word 里的 Zotero 插件继续维护

已知边界

• 仅支持 Windows + Word 桌面版
• 依赖本机可用的 Zotero Word 集成
• 相邻无间隔插入多个新引文时，Zotero 刷新后可能自动合并为复合引文字段
• 复杂受保护文档仍建议先做副本测试

开发复盘

详见：

• docs/DEVELOPMENT_REVIEW.md

License

MIT