Submit
Zhangchaokai1

zotero-word-mcp

Community Zhangchaokai1
Updated

zotero-word-mcp

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\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.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 刷新后可能自动合并为复合引文字段
  • 复杂受保护文档仍建议先做副本测试

开发复盘

详见：

  • docs/DEVELOPMENT_REVIEW.md

License

MIT

MCP Server · Populars

MCP Server · New