Klavis 仓库 Office-Word-MCP-Server 实战指南：让 AI Agent 可靠地创建与编辑 Word 文档

Klavis 仓库 Office-Word-MCP-Server 实战指南让 AI Agent 可靠地创建与编辑 Word 文档【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis导读本文聚焦于 Klavis 开源仓库中mcp_servers/local/word目录下内置的 Office-Word-MCP-Server一个基于 Model Context ProtocolMCP标准、专为 AI 助手设计的 Microsoft Word 文档操作服务。它把 Word 文档的创建、读取、排版、表格处理、批注提取乃至文档保护等能力封装为标准化的 MCP 工具让 Claude、Cursor 等 MCP 客户端能以自然语言直接驱动 .docx 文件的生产。读完本文你将掌握该服务器的安装配置、三种传输模式、全量工具清单与底层实现原理并能直接复用它来搭建AI 自动生成结构化报告 / 简历 / 技术文档的实战工作流。项目定位与架构总览Office-Word-MCP-Server 是 Klavis 仓库中负责文档生产力的本地 MCP 服务模块位于 mcp_servers/local/word。它扮演着 AI 助手与 Word 文档之间的桥梁通过 Model Context Protocol 将文档操作暴露为可被 Agent 调用的工具与资源。从源码结构看服务器采用分层模块化架构职责分离清晰入口层word_mcp_server.py 与 word_document_server/main.py 负责 FastMCP 实例初始化、工具注册与传输模式分发工具层word_document_server/tools/下按业务域拆分为 document_tools.py文档管理、content_tools.py内容添加、format_tools.py格式化、footnote_tools.py脚注尾注、protection_tools.py文档保护、comment_tools.py批注提取以及扩展文档工具核心实现层word_document_server/core/下的 tables.py、styles.py、footnotes.py、protection.py、comments.py 承载了基于 python-docx 的底层 XML 级操作工具函数层word_document_server/utils/提供文档读写、文件路径等通用辅助。技术底座由三个关键依赖构成见 requirements.txtFastMCPPython MCP 实现负责协议与工具注册、python-docxWord 文档对象模型操作、msoffcrypto-tool文档加密/解密、docx2pdfPDF 转换。项目元信息可在 pyproject.toml 中确认包名为office-word-mcp-server要求 Python 3.11并提供word_mcp_server命令行入口脚本。功能全景六类核心能力服务器通过register_tools()统一注册了 60 个 MCP 工具main.py可归纳为六大能力域能力域代表工具典型场景文档管理create_document、get_document_info、get_document_text、get_document_outline、list_available_documents、copy_document、convert_to_pdf、get_document_xml新建文档、分析文档结构、批量管理目录中的 .docx内容创建add_heading、add_paragraph、add_table、add_picture、add_page_break、insert_header_near_text、insert_line_or_paragraph_near_text、insert_numbered_list_near_text生成标题、正文、表格、图片、分页符与列表富文本格式化format_text、search_and_replace、delete_paragraph、create_custom_style、add_heading直接格式化指定段落/区间加粗、改色、换字体全局查找替换表格处理format_table、set_table_cell_shading、apply_table_alternating_rows、highlight_table_header、merge_table_cells*、set_table_cell_alignment、format_table_cell_text、set_table_cell_padding、set_table_column_width*、auto_fit_table_columns表头高亮、隔行着色、单元格合并、列宽控制等专业报表排版脚注尾注add_footnote_*、add_endnote_to_document、customize_footnote_style、delete_footnote_*、validate_document_footnotes学术/技术文档的注释体系维护文档保护与批注protect_document、unprotect_document、get_all_comments、get_comments_by_author、get_comments_for_paragraph密码保护、可编辑分区限制、批注审计安装部署三种方式与一条命令方式一Smithery 一键安装Claude Desktopnpx -y smithery/cli install GongRzhe/Office-Word-MCP-Server --client claude方式二本地源码安装前置要求为 Python 3.8 与 pip。克隆本仓库后进入模块目录安装依赖cd mcp_servers/local/word pip install -r requirements.txt依赖清单即 requirements.txt 中的五个包。若使用容器化部署仓库还提供了 Dockerfile基于python:3.11-slim镜像安装构建依赖后执行pip install --no-cache-dir .最终以word_mcp_server作为容器入口命令。容器编排可参考 smithery.yaml其startCommand声明为 stdio 类型并直接调用word_mcp_server。方式三setup_mcp.py 交互式脚本推荐项目提供了自动化设置脚本 setup_mcp.py一条命令完成全部流程python setup_mcp.py脚本会依次执行检查 Python 版本与 uv/uvx 是否就绪 → 创建/复用.venv虚拟环境并安装依赖 → 询问选择传输模式stdio / streamable-http / sse→ 生成对应的 mcp-config.json 并打印接入 Claude Desktop 的完整配置。从源码看setup_mcp.py它还会自动补全__init__.py、requirements.txt与.env.example等工程文件并支持三种配置生成策略本地 venv 的 python 直连、PyPI 包的 uvx 运行、Python 模块方式python -m word_document_server。三种传输模式与运行配置这是 README 之外、源码中最值得深挖的工程细节。服务器的传输层是可配置的全部通过环境变量控制main.py环境变量默认值说明MCP_TRANSPORTstdio传输模式合法值stdio、streamable-http、sse非法值自动回退 stdioMCP_HOST0.0.0.0HTTP/SSE 模式监听地址MCP_PORT8000监听端口优先读取 Render 平台的PORTMCP_PATH/mcpstreamable-http 模式端点路径MCP_SSE_PATH/sseSSE 模式端点路径FASTMCP_LOG_LEVELINFOFastMCP 2.8.1 所需的日志级别MCP_DEBUG未设置设为1时开启详细调试日志主入口在启动时会通过load_dotenv()加载.env文件并依据上述变量选择运行方式stdio默认mcp.run(transportstdio)与 Claude Desktop 等本地客户端通过标准输入输出通信配置最简单streamable-httpmcp.run(transportstreamable-http, host..., port..., path...)现代 Web 部署推荐便于远程调用与横向扩展ssemcp.run(transportsse, ...)兼容旧式 Server-Sent Events 客户端。验证 HTTP 服务可用性的命令setup 脚本会自动打印curl -X POST http://127.0.0.1:8000/mcp # streamable-http curl http://127.0.0.1:8000/sse # sse与 Claude Desktop 集成本地安装后的配置将如下片段合并进 Claude Desktop 配置文件其中args指向本模块的入口脚本{ mcpServers: { word-document-server: { command: python, args: [/path/to/word_mcp_server.py] } } }仓库自带的 mcp-config.json 是生成后的实际范例展示了更完整的形态command指向虚拟环境中的 pythonargs指向入口脚本env中设置PYTHONPATH与MCP_TRANSPORT。免安装的 uvx 方式若通过 PyPI 安装包且本机有 uvx可直接使用{ mcpServers: { word-document-server: { command: uvx, args: [--from, office-word-mcp-server, word_mcp_server] } } }配置文件位置macOS 为~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 为%APPDATA%\Claude\claude_desktop_config.json。修改后需重启 Claude Desktop 使配置生效。典型自然语言指令配置完成后Agent 可直接执行以下类型的指令README 原始示例可直接用于实测Create a new document called report.docx with a title pageAdd a heading and three paragraphs to my documentAdd my name in Helvetica 36pt bold at the top of the documentAdd a section heading Summary in Helvetica 14pt bold with a bottom borderAdd a paragraph in Times New Roman 14pt with italic blue textInsert a bulleted list after the paragraph containing IntroductionInsert a numbered list with items: First step, Second step, Third stepInsert a 4x4 table with sales dataFormat the word important in paragraph 2 to be bold and redSearch and replace all instances of old term with new termExtract all comments from my documentShow me all comments by John DoeMake the text in table cell (1,2) bold and blue with 14pt fontAdd 10 points of padding to all sides of the header cellsSet the first column width to 50 points and auto-fit the remaining columnsApply alternating row colors to make the table more readable工具 API 详解以下签名均以源码注册处为准main.py可直接在 MCP 客户端中按名调用。文档创建与属性create_document(filename, titleNone, authorNone) # 新建文档并可写入元数据 get_document_info(filename) # 查看文档属性与统计 get_document_text(filename) # 提取全部文本 get_document_outline(filename) # 获取大纲/结构 list_available_documents(directory.) # 列出目录下所有 .docx copy_document(source_filename, destination_filenameNone) # 复制文档 convert_to_pdf(filename, output_filenameNone) # 转换为 PDF get_document_xml(filename) # 导出原始 XML调试利器内容添加add_heading(filename, text, level1, font_nameNone, font_sizeNone, boldNone, italicNone, border_bottomFalse) # level: 1-9 级标题border_bottomTrue 生成带下边框的分节标题 add_paragraph(filename, text, styleNone, font_nameNone, font_sizeNone, boldNone, italicNone, colorNone) # color 为无 # 前缀的十六进制 RGB如 000000 黑色 add_table(filename, rows, cols, dataNone) # data 为二维列表 add_picture(filename, image_path, widthNone) # width 按比例缩放 add_page_break(filename)相对定位的高级内容操作这些工具实现了围绕已有文本/段落索引插入内容是构造长文档工作流的关键# 在目标文本前/后插入标题默认 Heading 1 样式 insert_header_near_text(filename, target_textNone, header_titleNone, positionafter, header_styleHeading 1, target_paragraph_indexNone) # 在目标文本前/后插入段落 insert_line_or_paragraph_near_text(filename, target_textNone, line_textNone, positionafter, line_styleNone, target_paragraph_indexNone) # 插入项目符号/编号列表底层走正确 XML 编号结构 insert_numbered_list_near_text(filename, target_textNone, list_itemsNone, positionafter, target_paragraph_indexNone, bullet_typebullet) # bullet_type: bullet 生成圆点项目符号number 生成 1, 2, 3... 编号列表此外 main.py 还注册了两个批量改写工具replace_paragraph_block_below_header替换某标题下方的段落块避开目录 TOC与replace_block_between_manual_anchors替换两个锚点文本之间的全部内容适用于AI 迭代更新文档章节的场景。内容提取与文本格式化get_document_text(filename) get_paragraph_text_from_document(filename, paragraph_index) find_text_in_document(filename, text_to_find, match_caseTrue, whole_wordFalse) format_text(filename, paragraph_index, start_pos, end_pos, boldNone, italicNone, underlineNone, colorNone, font_sizeNone, font_nameNone) search_and_replace(filename, find_text, replace_text) delete_paragraph(filename, paragraph_index) create_custom_style(filename, style_name, boldNone, italicNone, font_sizeNone, font_nameNone, colorNone, base_styleNone)表格格式化全家桶format_table(filename, table_index, has_header_rowNone, border_styleNone, shadingNone) # border_style: none/single/double/thick set_table_cell_shading(filename, table_index, row_index, col_index, fill_color, patternclear) # fill_color 如 FF0000 或标准色名 apply_table_alternating_rows(filename, table_index, color1FFFFFF, color2F2F2F2) highlight_table_header(filename, table_index, header_color4472C4, text_colorFFFFFF) # 单元格合并0 基索引矩形区域 merge_table_cells(filename, table_index, start_row, start_col, end_row, end_col) merge_table_cells_horizontal(filename, table_index, row_index, start_col, end_col) merge_table_cells_vertical(filename, table_index, col_index, start_row, end_row) # 对齐 set_table_cell_alignment(filename, table_index, row_index, col_index, horizontalleft, verticaltop) set_table_alignment_all(filename, table_index, horizontalleft, verticaltop) # 单元格文本格式化 format_table_cell_text(filename, table_index, row_index, col_index, text_contentNone, boldNone, italicNone, underlineNone, colorNone, font_sizeNone, font_nameNone) # 单元格内边距unit: points 或 percent set_table_cell_padding(filename, table_index, row_index, col_index, topNone, bottomNone, leftNone, rightNone, unitpoints) # 列宽与自动适应 set_table_column_width(filename, table_index, col_index, width, width_typepoints) set_table_column_widths(filename, table_index, widths, width_typepoints) set_table_width(filename, table_index, width, width_typepoints) auto_fit_table_columns(filename, table_index)这些工具在底层均有对应的 XML 级实现。以 tables.py 为例set_cell_shading通过构造w:shd元素写入tcPr自动剥离#前缀并统一为大写十六进制如#FF0000→FF0000merge_cells先对行列索引做边界校验再调用 python-docx 的cell.merge()set_column_width支持dxa磅值×20、pct百分比×50、auto三种单位换算后写入w:tcW元素auto_fit_table则在tblPr中注入w:tblLayout w:typeautofit/。理解了这些实现就能预判 README 故障排查中的两个典型坑自动适应会覆盖手动列宽、颜色必须是无 # 的 6 位十六进制或标准色名。批注提取get_all_comments(filename) # 全部批注 get_comments_by_author(filename, author) # 按作者过滤 get_comments_for_paragraph(filename, paragraph_index) # 指定段落每个批注附带作者、日期、正文等元数据对应 comments.py 的实现便于 Agent 做文档审阅与意见汇总。文档保护密码加密与受限编辑在 README 的Document Protection特性之上protection.py 揭示了具体的实现机制protect_document(filename, password)先对密码做哈希并生成同名的.protection元数据文件记录保护类型、应用时间、可编辑分区、签名信息等随后调用msoffcrypto库对 .docx 执行真正的文件级加密加密结果写入临时文件后原子替换原文档unprotect_document(filename, password)读取元数据并解密还原受限编辑模式支持指定可编辑分区editable_sections实现整篇锁定、局部可改的合同/模板场景数字签名与完整性校验对应 protection.py 中的signature信息记录与verify类逻辑。测试与验证仓库提供了两层验证手段脚本级测试test_formatting.py 以asyncio方式逐个调用create_document、add_paragraph、add_heading覆盖Helvetica 36pt 加粗姓名行、14pt 标题行、带下边框的分节标题、Times New Roman 正文等 README 示例指令可直接运行验证格式化参数字体族、字号、加粗、边框确实生效单元测试tests/test_convert_to_pdf.py 覆盖 PDF 转换功能可使用pytest运行。故障排查速查表现象原因与处理标题/表格操作报缺少样式文档模板缺少标准样式服务器会尝试自动创建或退化为直接格式化建议使用带标准 Word 样式的模板读写权限失败确保进程对文档路径有读写权限对锁定文档先用copy_document生成可编辑副本检查文件属主与权限位图片插入失败使用绝对路径优先 JPEG/PNG确认文件大小与权限单元格索引越界行/列索引均为0 基先核对表格尺寸颜色不生效使用无#前缀的 6 位十六进制如FF0000或标准色名内边距单位混淆显式指定unitpoints或unitpercent列宽被覆盖auto_fit_table_columns会覆盖手动列宽二者不要混用单元格文本格式丢失先写入单元格内容再调用format_table_cell_text应用格式调试时可开启详细日志Linux/macOS 执行export MCP_DEBUG1Windows 执行set MCP_DEBUG1HTTP 模式下的网络问题可结合上文 curl 命令直连端点定位。实战组合建议将上述工具串联即可构成完整的AI 文档工厂流水线create_document新建带标题与作者的文档add_headingadd_paragraph携带font_name/font_size/bold/color直接格式化逐段构建目录与正文减少往返调用add_tablehighlight_table_headerapply_table_alternating_rowsset_table_column_widths生成专业报表insert_numbered_list_near_text在关键段落附近插入步骤列表add_footnote_robust维护脚注体系validate_document_footnotes校验合规性protect_document对交付件加密convert_to_pdf输出最终版get_all_comments/get_comments_by_author完成审阅闭环。结语Office-Word-MCP-Server 把 Word 的复杂对象模型压缩成一组语义清晰、可组合的 MCP 工具配合多传输模式与完善的配置脚本是 Klavis 仓库中让 AI Agent 可靠地生产办公文档的现成基础设施。无论是本地 Claude Desktop 的自然语言排版还是远程 streamable-http 的自动化报表流水线都能基于本模块快速落地。使用前请记住 README 的提醒该服务器会直接读写你系统上的文档文件在客户端确认任何操作前务必先核实请求的适当性。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考