README.md
Insert native Zotero citations and bibliographies into Microsoft Word.
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_DIRZotero 数据目录，例如D:\Zotero\ZoteroFileZOTERO_SQLITE_PATH指向zotero.sqliteZOTERO_WORD_DLL指向libzoteroWinWordIntegration.dll
如果不显式设置，程序会优先从 Zotero prefs.js 自动发现数据目录。
MCP 工具
`insert_citation`
向 Word 文档插入 Zotero 原生引文。
主要参数：
dockeysfind_textplacementstyle_idlibrary_idprefixsuffixrefresh_afterwait_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.pyWord COM 基础桥接src/zotero_word_mcp/native_bridge.pyZotero 原生字段与刷新逻辑src/zotero_word_mcp/server.pyMCP 工具封装docs/DEVELOPMENT_REVIEW.md开发复盘与技术路线说明
与静态引用方案的区别
静态方案通常是：
- 正文写
[1] - 文末写普通文本参考文献
- 再靠 Word 交叉引用或脚本刷新
这类方案容易控，但不是 Zotero 原生动态引文。
本项目写入的是 Zotero 官方 Word 集成可识别的字段，因此：
- Zotero 可以继续接管这份文档
- 用户后续仍能用 Word 里的 Zotero 插件继续维护
已知边界
- 仅支持 Windows + Word 桌面版
- 依赖本机可用的 Zotero Word 集成
- 相邻无间隔插入多个新引文时，Zotero 刷新后可能自动合并为复合引文字段
- 复杂受保护文档仍建议先做副本测试
开发复盘
详见：
License
MIT
Tools (6)
insert_citationInserts a Zotero native citation into the Word document.insert_bibliographyInserts a Zotero native bibliography field into the Word document.refresh_documentTriggers the official Zotero Refresh command and waits for field resolution.list_fieldsLists all Zotero native fields and document preferences in the current document.set_document_styleSets the Zotero CSL style for the document without triggering an immediate refresh.probe_documentVerifies if the current document is recognized by the official Zotero Word integration.Environment Variables
ZOTERO_DATA_DIRPath to the Zotero data directoryZOTERO_SQLITE_PATHPath to the zotero.sqlite fileZOTERO_WORD_DLLPath to the libzoteroWinWordIntegration.dll fileConfiguration
claude_desktop_config.json
{"mcpServers": {"zotero-word": {"command": "python", "args": ["-m", "zotero_word_mcp"]}}}Try it
→Insert a citation for the paper with key 'Smith2023' into my current Word document.
→Add a bibliography section at the end of my document.
→Refresh the Zotero citations in my document to ensure all fields are updated.
→List all Zotero fields currently present in this Word document.
→Set the citation style of this document to APA 7th edition.