Office-Word-MCP-Server在Cursor中使用方法

路西法012025-12-17 18:05

Office-Word-MCP-Server在Cursor中使用方法

Office-Word-MCP-Server 实现了 Model Context Protocol，
将 Word 文档操作以工具（tools）和资源（resources）的形式暴露出来。
它在 AI 助手与本地/服务器上的 Word 文档之间搭建了一座桥梁，使得助手能够创建文档、添加内容、进行格式化和文档分析等。

该服务器采用模块化架构，将核心功能、工具和实用函数解耦，便于维护和扩展，后续可以方便地增加新的文档操作能力。

功能特性

文档管理

  • 创建文档：创建带有元数据（标题、作者等）的 Word 文档
  • 文本提取与结构分析：提取全文文本、查看文档大纲结构
  • 文档属性查看：查看文档属性和统计信息
  • 文档列表：列出目录中可用的文档
  • 文档复制：对现有文档创建副本
  • 文档合并：将多个文档合并为一个
  • 格式转换：将 Word 文档转换为 PDF

内容创建

  • 标题与段落：添加不同级别的标题，支持字体、字号、加粗、斜体、边框等直接格式设置
  • 普通段落：插入带样式的段落文本，支持字体、字号、加粗、斜体、颜色等
  • 表格创建：创建自定义数据表格
  • 图片插入：插入图片并按比例缩放
  • 分页管理：插入分页符
  • 列表：插入项目符号列表和编号列表，并正确生成 Word 所需的 XML 结构
  • 脚注与尾注：添加脚注、尾注，并支持脚注与尾注之间的转换及样式定制
  • 相对位置插入：可以基于目标文本或段落索引，在其前后插入标题或段落内容

富文本格式

  • 对文档中某一段落内的特定文本范围进行加粗、斜体、下划线等格式化
  • 修改文本颜色、字体属性
  • 创建并应用自定义样式
  • 在整个文档中执行查找与替换
  • 对表格单元格中的文本进行局部格式设置（如加粗、斜体、颜色、字号等）
  • 支持丰富的颜色定义（标准颜色名和 16 进制颜色）
  • 在内容创建时直接应用所需格式，减少多次调用
  • 为章节标题添加底边框等视觉分隔

表格格式

  • 设置表格边框和整体样式
  • 创建具有独立格式的表头行
  • 单元格底纹填充和自定义边框
  • 为报表型表格设置清晰的结构和可读性
  • 单元格背景色设置，支持多种颜色
  • 行交替配色，提高表格可读性
  • 加强表头高亮效果，支持自定义背景色和字体颜色
  • 单元格中文本的加粗、斜体、下划线、颜色、字体大小、字体族等
  • 单元格内边距控制（四边可独立设置）
  • 单元格对齐（水平、垂直居中/对齐）
  • 单元格合并（横向、纵向、矩形区域合并）
  • 列宽设置（支持点、百分比、自适应等）
  • 列宽自适应功能
  • 专门为技术文档和说明文档提供专业风格的"提示/标注表格"（callout table）

高级文档操作

  • 删除指定段落
  • 基于目标文本或段落索引，在其前后插入内容
  • 插入项目符号和编号列表，并生成正确的 Word XML 编号结构
  • 在目标位置前后插入标题和段落
  • 创建自定义文档样式，并在文档中统一应用
  • 对指定范围文本进行精细格式化控制
  • 支持点和百分比两种单位的内边距设置
  • 通过对齐、间距、边距等综合控制，提升表格排版质量

文档保护

  • 为文档添加密码保护
  • 配置受限制编辑，允许指定区域可编辑
  • 添加数字签名
  • 验证文档的真实性与完整性

批注提取

  • 提取文档中所有批注
  • 按作者过滤批注
  • 获取特定段落对应的批注
  • 获取批注元数据（作者、时间、内容等）

安装

通过 Smithery 安装（推荐用于 Claude Desktop）

使用 Smithery 为 Claude Desktop 自动安装：

bash 复制代码 
npx -y @smithery/cli install @GongRzhe/Office-Word-MCP-Server --client claude

前置条件

  • Python 3.8 或更高版本
  • 已安装 pip

基本安装方式

bash 复制代码 
# 克隆仓库
git clone https://github.com/GongRzhe/Office-Word-MCP-Server.git
cd Office-Word-MCP-Server

# 安装依赖
pip install -r requirements.txt

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/

使用安装脚本

也可以使用项目内提供的 setup_mcp.py 脚本，该脚本会自动执行：

  • 检查环境依赖
  • 创建虚拟环境
  • 安装依赖
  • 生成 MCP 配置
bash 复制代码 
python setup_mcp.py

在 Claude for Desktop 中使用

配置

方法一：本地安装后直接调用
  1. 安装完成后，在 Claude for Desktop 的配置文件中添加以下内容：
json 复制代码 
{
  "mcpServers": {
    "word-document-server": {
      "command": "python",
      "args": ["/path/to/word_mcp_server.py"]
    }
  }
}

将 "/path/to/word_mcp_server.py" 替换为本地实际路径。

方法二：使用 uvx（无需手动克隆仓库）
  1. 你也可以使用 uvx 以"即用即拉取"的方式运行服务器：
json 复制代码 
{
  "mcpServers": {
    "word-document-server": {
      "command": "uvx",
      "args": ["--from", "office-word-mcp-server", "word_mcp_server"]
    }
  }
}

  1. 配置文件位置：

    • macOS ：~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows ：%APPDATA%\\Claude\\claude_desktop_config.json

  2. 修改完成后，重启 Claude for Desktop 使配置生效。

示例对话指令

配置完成后，你可以对 Claude 说例如：

  • "创建一个名为 report.docx 的新文档，并生成一个标题页"
  • "在当前文档中添加一个一级标题和三段正文"
  • "在文档顶部用 Helvetica 36pt 加粗显示我的名字"
  • "添加一个标题为 'Summary' 的节标题，使用 Helvetica 14pt 加粗并带下边框"
  • "添加一段 Times New Roman 14pt 的段落，斜体蓝色字体"
  • "在包含 'Introduction' 的那段后面插入一个项目符号列表"
  • "插入一个编号列表，包含 'First step'、'Second step'、'Third step'"
  • "在 'Summary' 标题后添加几个要点列表"
  • "插入一个 4x4 的销售数据表格"
  • "将第 2 段中所有 'important' 一词加粗并设置为红色"
  • "在整个文档中把 'old term' 替换为 'new term'"
  • "创建并应用一个用于章节标题的自定义样式"
  • "对当前文档中的表格应用统一的格式"
  • "提取文档中的所有批注"
  • "只显示 John Doe 添加的批注"
  • "获取第 3 段对应的所有批注"
  • "将表格单元格 (1,2) 中的文字设为加粗、蓝色、14pt 字号"
  • "将表头单元格的四边内边距设置为 10pt"
  • "创建一个带蓝色对勾图标和白色文字的提示表格"
  • "将第一列列宽设置为 50pt，其余列自动适配"
  • "为表格应用交替行底色以提高可读性"

API 参考

下面为核心 Python API 示例，方便在代码中直接调用：

文档创建与属性

python 复制代码 
create_document(filename, title=None, author=None)
get_document_info(filename)
get_document_text(filename)
get_document_outline(filename)
list_available_documents(directory=".")
copy_document(source_filename, destination_filename=None)
convert_to_pdf(filename, output_filename=None)

内容添加

python 复制代码 
add_heading(filename, text, level=1, font_name=None, font_size=None,
            bold=None, italic=None, border_bottom=False)
add_paragraph(filename, text, style=None, font_name=None, font_size=None,
              bold=None, italic=None, color=None)
add_table(filename, rows, cols, data=None)
add_picture(filename, image_path, width=None)
add_page_break(filename)

高级内容操作

python 复制代码 
# 相对现有文本或段落索引插入内容
insert_header_near_text(filename, target_text=None, header_title=None,
                        position='after', header_style='Heading 1',
                        target_paragraph_index=None)

insert_line_or_paragraph_near_text(filename, target_text=None, line_text=None,
                                   position='after', line_style=None,
                                   target_paragraph_index=None)

# 使用正确的 XML 编号结构插入项目符号或编号列表
insert_numbered_list_near_text(filename, target_text=None, list_items=None,
                               position='after', target_paragraph_index=None,
                               bullet_type='bullet')
# bullet_type 可选值：
#   'bullet' - 创建项目符号列表（•）
#   'number' - 创建编号列表（1, 2, 3, ...）

内容提取

python 复制代码 
get_document_text(filename)
get_paragraph_text_from_document(filename, paragraph_index)
find_text_in_document(filename, text_to_find, match_case=True, whole_word=False)

文本格式

python 复制代码 
format_text(filename, paragraph_index, start_pos, end_pos, bold=None,
            italic=None, underline=None, color=None, font_size=None, font_name=None)
search_and_replace(filename, find_text, replace_text)
delete_paragraph(filename, paragraph_index)
create_custom_style(filename, style_name, bold=None, italic=None,
                    font_size=None, font_name=None, color=None, base_style=None)

表格格式

python 复制代码 
format_table(filename, table_index, has_header_row=None,
             border_style=None, shading=None)
set_table_cell_shading(filename, table_index, row_index, col_index, 
                       fill_color, pattern="clear")
apply_table_alternating_rows(filename, table_index, 
                             color1="FFFFFF", color2="F2F2F2")
highlight_table_header(filename, table_index, 
                       header_color="4472C4", text_color="FFFFFF")

# 单元格合并
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,
                         horizontal="left", vertical="top")
set_table_alignment_all(filename, table_index, 
                        horizontal="left", vertical="top")

# 单元格文字格式
format_table_cell_text(filename, table_index, row_index, col_index,
                       text_content=None, bold=None, italic=None, underline=None,
                       color=None, font_size=None, font_name=None)

# 单元格内边距
set_table_cell_padding(filename, table_index, row_index, col_index,
                       top=None, bottom=None, left=None, right=None, unit="points")

# 列宽管理
set_table_column_width(filename, table_index, col_index, width, width_type="points")
set_table_column_widths(filename, table_index, widths, width_type="points")
set_table_width(filename, table_index, width, width_type="points")
auto_fit_table_columns(filename, table_index)

批注提取

python 复制代码 
get_all_comments(filename)
get_comments_by_author(filename, author)
get_comments_for_paragraph(filename, paragraph_index)

故障排查

常见问题

  1. 缺少样式

    • 某些文档可能缺少标题或表格操作所需的样式
    • 服务器会尝试自动创建缺失样式或采用直接格式
    • 为获得最佳效果，建议基于包含标准 Word 样式的模板创建文档

  2. 权限问题

    • 请确保服务器对目标路径具有读写权限
    • 可使用 copy_document 先生成可编辑副本
    • 如操作失败，请检查文件所有者和访问权限

  3. 图片插入异常

    • 建议使用图片的绝对路径
    • 确认图片格式（推荐 JPEG、PNG）
    • 检查图片文件大小及访问权限

  4. 表格格式问题

    • 单元格索引错误：行列索引采用 0 基（从 0 开始），需确保在表格范围内
    • 颜色格式错误 ：使用不带 # 的十六进制颜色（例如 "FF0000" 表示红色）或标准颜色名
    • 内边距单位混淆 ：设置单元格内边距时请显式指定 "points" 或 "percent"
    • 列宽冲突：自动适应列宽功能可能会覆盖手动列宽设置
    • 文本格式残留：建议先更新单元格内容，再应用文本格式，以获得更稳定的效果

调试

通过设置环境变量启用详细日志输出：

bash 复制代码 
export MCP_DEBUG=1  # Linux/macOS
set MCP_DEBUG=1     # Windows
相关推荐
飞哥数智坊11 小时前
Cursor 可视化编辑器实测：前端效率新利器，但仍需完善
人工智能·ai编程·cursor
Light6011 小时前
【MCP原生时代】第2篇｜前端如何舞动 MCP：新一代交互范式——从 Hook 到流式渲染，打造 AI 原生前端体验
状态模式·前端架构·mcp·react hook·流式渲染·ai交互
程序员鱼皮1 天前
全面封禁 Cursor！又一家大厂出手了
程序员·ai编程·cursor
渣渣苏1 天前
MCP实战指南
mcp
爬点儿啥2 天前
[Ai Agent] 10 MCP基础：快速编写你自己的MCP服务器（Server）
人工智能·ai·langchain·agent·transport·mcp
飞哥数智坊2 天前
今年我试了十几款 AI 编程工具，最终只留下这 3 个
ai编程·cursor·trae
树獭叔叔2 天前
一种上下文工程的范式-Letta（MemGPT）项目拆解
aigc·openai·cursor
王小酱2 天前
Cursor 的 Debug模式的核心理念和使用流程
前端·cursor
小鱼儿亮亮2 天前
Agents SDK+MCP智能体开发
agent·mcp
热门推荐
01GitHub 镜像站点02UV安装并设置国内源03Linux下V2Ray安装配置指南04在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）05【AutoGLM部署】本地私有化部署AI手机Agent06Open-AutoGLM Windows 安装部署教程07Cursor 又偷偷更新，这个功能太实用：Visual Editor for Cursor Browser08安娜的档案(Anna’s Archive) 镜像网站/国内最新可访问入口（持续更新）09Labelme从安装到标注：零基础完整指南10BongoCat - 跨平台键盘猫动画工具