Office-Word-MCP-Server 完整部署指南

本文记录了在 Windows 环境下部署 Office-Word-MCP-Server 的完整过程，包括遇到的问题及解决方案。

目录

• 背景介绍
• 环境准备
• 两种部署方式
  • 方式一：stdio 模式（本地通信）
  • 方式二：HTTP/SSE 模式（网络通信）
• 部署过程中遇到的问题
• 使用示例
• 总结

---

背景介绍

Office-Word-MCP-Server 是一个基于 Model Context Protocol (MCP) 的服务器，可以让 AI 助手通过标准化接口操作 Microsoft Word 文档。

主要功能包括：

• 文档创建与管理
• 内容添加（标题、段落、表格、图片、列表等）
• 文本格式化（字体、颜色、样式）
• 表格格式化（边框、单元格合并、对齐）
• 文档保护与注释提取
• Word 转 PDF

环境准备

系统要求

• 操作系统: Windows 10/11
• Python: 3.8 或更高版本
• 包管理器: uv（推荐）或 pip

安装 uv 包管理器

# 使用 PowerShell 安装 uv
irm https://astral.sh/uv/install.ps1 | iex

安装完成后，重启终端验证：

uv --version

---

两种部署方式

Office-Word-MCP-Server 支持两种部署模式，适用于不同的使用场景。

方式一：stdio 模式（本地通信）

适用场景

• 本地应用程序（如 Claude Desktop、Cursor、Lingma 编辑器等）
• 不需要跨网络访问
• 资源占用更少

配置步骤

1. 在 MCP 配置文件中添加服务器

对于 Lingma 编辑器，编辑 C:\Users\<用户名>\.lingma\lingma_mcp.json：

{
  "mcpServers": {
    "office-word-mcp-server": {
      "command": "uvx",
      "args": [
        "--from",
        "office-word-mcp-server",
        "word_mcp_server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

对于 Claude Desktop，编辑配置文件：

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

{
  "mcpServers": {
    "office-word-mcp-server": {
      "command": "uvx",
      "args": ["--from", "office-word-mcp-server", "word_mcp_server"]
    }
  }
}

2. 重启应用程序

保存配置后，重启 Claude Desktop 或 Lingma 编辑器以加载 MCP 服务器。

优点

• ✅ 配置简单，无需手动启动服务
• ✅ 自动随应用启动
• ✅ 无需网络配置
• ✅ 更安全（仅本地访问）

缺点

• ❌ 仅限本地应用访问
• ❌ 无法用于容器化应用（如 Docker 中的 N8N）

---

方式二：HTTP/SSE 模式（网络通信）

适用场景

• 容器化应用（如 Docker 中运行的 N8N）
• 需要远程访问
• 多个客户端共享同一个 MCP 服务器

配置步骤

1. 获取本机 IP 地址

Get-NetIPAddress -AddressFamily IPv4 | Where-Object {$_.IPAddress -like "192.168.*" -or $_.IPAddress -like "10.*"} | Select-Object IPAddress

示例输出：

IPAddress    
---------    
192.168.1.100

2. 创建启动脚本

创建 start_word_mcp_http.bat 文件：

@echo off
echo Starting Office Word MCP Server in HTTP/SSE mode...
echo Server will run on http://0.0.0.0:8000/sse
echo.
set MCP_TRANSPORT=sse
set HOST=0.0.0.0

uvx --from office-word-mcp-server word_mcp_server

pause

3. 启动服务器

双击运行 start_word_mcp_http.bat，或在 PowerShell 中执行：

$env:MCP_TRANSPORT="sse"; $env:HOST="0.0.0.0"; uvx --from office-word-mcp-server word_mcp_server

成功启动后会看到：

Transport: sse
Starting Word Document MCP Server with sse transport...
Server running on SSE transport at http://0.0.0.0:8000/sse

╭──────────────────────────────────────────────────────────────────────────────╮
│                         ▄▀▀ ▄▀█ █▀▀ ▀█▀ █▀▄▀█ █▀▀ █▀█                        │
│                         █▀  █▀█ ▄▄█  █  █ ▀ █ █▄▄ █▀▀                        │
│                                                                              │
│                                FastMCP 2.13.3                                │
│                                                                              │
│                   🖥  Server name: Word Document Server                       │
│                   📦 Transport:   SSE                                        │
│                   🔗 Server URL:  http://0.0.0.0:8000/sse                    │
╰──────────────────────────────────────────────────────────────────────────────╯

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

4. 在 N8N 中配置

在 N8N 的 MCP Client 节点中填入以下参数：

参数	值
Endpoint	http://192.168.1.100:8000/sse
Server Transport	HTTP Streamable
Authentication	None
Tools to Include	All

⚠️ 注意：将 192.168.1.100 替换为您的实际本机 IP 地址。

5. 测试连接

在浏览器中访问 http://192.168.1.100:8000/sse，应该能看到连接成功。

优点

• ✅ 支持容器化应用访问
• ✅ 可远程访问
• ✅ 多客户端共享
• ✅ 便于调试（可查看请求日志）

缺点

• ❌ 需要手动启动服务
• ❌ 需要配置网络和防火墙
• ❌ 占用端口资源

---

部署过程中遇到的问题

问题 1：端口设置无效

现象：
在批处理脚本中设置了 PORT=3000，但服务器实际运行在 8000 端口。

原因：
office-word-mcp-server 使用 FastMCP 框架，该框架在 SSE 模式下固定使用 8000 端口，不读取 PORT 环境变量。

解决方案：
删除 PORT 环境变量设置，直接使用默认的 8000 端口。更新后的脚本：

set MCP_TRANSPORT=sse
set HOST=0.0.0.0
# 不需要设置 PORT

---

问题 2：容器内 N8N 无法访问 localhost

现象：
N8N 在 Docker 容器中运行，配置 http://localhost:3000/sse 无法连接。

原因：
Docker 容器有独立的网络命名空间，容器内的 localhost 指向容器自身，而不是宿主机。

解决方案：

方案 A：使用宿主机 IP（推荐）

1. 获取宿主机 IP 地址（如 192.168.1.100）
2. MCP 服务器绑定到 0.0.0.0（所有网络接口）
3. 在 N8N 中使用宿主机 IP：http://192.168.1.100:8000/sse

方案 B：使用 Docker 特殊域名

如果 Docker 支持，可以在启动 N8N 容器时添加：

docker run -d \
  --name n8n \
  -p 5678:5678 \
  --add-host=host.docker.internal:host-gateway \
  n8nio/n8n:latest

然后在 N8N 中使用：http://host.docker.internal:8000/sse

---

问题 3：MCP Client 传递了额外参数导致验证错误

现象：
N8N 的 MCP Client 节点调用工具时出现验证错误：

Error validating tool 'create_document': 4 validation errors
  sessionId - Unexpected keyword argument
  action - Unexpected keyword argument
  chatInput - Unexpected keyword argument
  toolCallId - Unexpected keyword argument

原因：
N8N 的 MCP Client 节点在调用工具时，错误地将 N8N 内部参数（sessionId、action、chatInput、toolCallId）传递给了 MCP 工具。

解决方案：

这是 N8N MCP Client 节点的参数映射问题。在 N8N 中正确配置工具参数：

1. 在 MCP Client 节点中，不要直接使用聊天输入
2. 需要明确指定工具调用和参数
3. 例如调用 create_document 工具时，只传递必需参数：

   {
     "filename": "test.docx",
     "title": "测试文档",
     "author": "张三"
   }
   

⚠️ 提示：这个问题可能是 N8N 的 MCP Client 节点版本问题，建议更新到最新版本或查看官方文档。

---

问题 4：防火墙阻止连接

现象：
服务器启动正常，但 N8N 无法连接。

解决方案：

1. 检查 Windows 防火墙是否阻止了 8000 端口：

# 添加防火墙规则允许 8000 端口入站
New-NetFirewallRule -DisplayName "MCP Server 8000" -Direction Inbound -LocalPort 8000 -Protocol TCP -Action Allow

2. 或临时关闭防火墙测试（不推荐在生产环境）：

Set-NetFirewallProfile -Profile Domain,Public,Private -Enabled False

---

问题 5：端口被占用

现象：
启动时报错：

ERROR: [Errno 10048] error while attempting to bind on address ('0.0.0.0', 8000):
通常每个套接字地址(协议/网络地址/端口)只允许使用一次。

解决方案：

1. 查找占用 8000 端口的进程：

netstat -ano | findstr :8000

2. 终止占用端口的进程：

# 假设进程 ID 是 1234
taskkill /PID 1234 /F

3. 或者修改服务器端口（如果支持）

---

使用示例

在 Lingma 编辑器中使用（stdio 模式）

配置完成后，直接在聊天中请求：

请创建一个名为"项目报告.docx"的文档，添加一个标题"2025年度项目总结"，
然后添加三个段落介绍项目背景、进展和成果。

在 N8N 中使用（HTTP 模式）

1. 添加 MCP Client 节点
2. 配置连接信息（如前所述）
3. 选择工具，例如 create_document
4. 设置参数：

   {
     "filename": "report.docx",
     "title": "月度报告",
     "author": "AI 助手"
   }
   

5. 执行节点

常用工具示例

创建文档

{
  "tool": "create_document",
  "params": {
    "filename": "test.docx",
    "title": "测试文档",
    "author": "张三"
  }
}

添加标题

{
  "tool": "add_heading",
  "params": {
    "filename": "test.docx",
    "text": "第一章 引言",
    "level": 1,
    "font_name": "Microsoft YaHei",
    "font_size": 16,
    "bold": true
  }
}

添加段落

{
  "tool": "add_paragraph",
  "params": {
    "filename": "test.docx",
    "text": "这是一个测试段落，包含一些示例文本。",
    "font_name": "SimSun",
    "font_size": 12,
    "color": "000000"
  }
}

添加表格

{
  "tool": "add_table",
  "params": {
    "filename": "test.docx",
    "rows": 3,
    "cols": 4,
    "data": [
      ["姓名", "年龄", "职位", "部门"],
      ["张三", "28", "工程师", "技术部"],
      ["李四", "32", "经理", "销售部"]
    ]
  }
}

文档转 PDF

{
  "tool": "convert_to_pdf",
  "params": {
    "filename": "test.docx",
    "output_filename": "test.pdf"
  }
}

---

两种模式对比

特性	stdio 模式	HTTP/SSE 模式
适用场景	本地应用	容器化/远程访问
配置复杂度	⭐ 简单	⭐⭐ 中等
启动方式	自动（随应用启动）	手动启动脚本
网络需求	无	需要开放端口
安全性	⭐⭐⭐ 高（仅本地）	⭐⭐ 中（需配置防火墙）
多客户端	❌ 不支持	✅ 支持
调试便利性	⭐⭐ 中等	⭐⭐⭐ 高（有日志）
资源占用	⭐⭐⭐ 低	⭐⭐ 中等
典型应用	Claude Desktop, Cursor, Lingma	Docker N8N, 远程调用

---

故障排除清单

服务无法启动

• 检查 Python 版本（需要 3.8+）
• 检查 uv 是否正确安装
• 检查端口 8000 是否被占用
• 查看启动日志中的错误信息

无法连接

• 确认服务器正在运行
• 检查防火墙设置
• 验证 IP 地址是否正确
• 确认容器网络配置（Docker）
• 尝试用浏览器访问端点测试

工具调用失败

• 检查参数格式是否正确
• 确认文件路径存在且可写
• 查看服务器日志中的详细错误
• 验证 Microsoft Word 文档格式兼容性

---

最佳实践建议

1. 选择合适的部署模式

• 个人使用 + 本地应用 → stdio 模式
• 团队协作 + 容器化部署 → HTTP 模式

2. 安全建议

• HTTP 模式下，不要将服务暴露到公网
• 在生产环境中添加认证机制
• 定期更新 office-word-mcp-server 版本

3. 性能优化

• 批量操作时，尽量合并多个小操作
• 大文件操作考虑异步处理
• 定期清理临时文档

4. 文档管理

• 使用绝对路径指定文件位置
• 建立统一的文档命名规范
• 定期备份重要文档

---

参考资源

• Office-Word-MCP-Server GitHub
• Model Context Protocol 官方文档
• FastMCP 文档
• python-docx 文档
• N8N 官方文档

---

总结

本文详细介绍了 Office-Word-MCP-Server 的两种部署方式：

1. stdio 模式：适合本地应用（Claude Desktop、Lingma 编辑器），配置简单，自动启动
2. HTTP/SSE 模式：适合容器化应用（Docker N8N），支持远程访问和多客户端

部署过程中主要遇到的问题包括：

• 端口配置不生效（FastMCP 固定使用 8000）
• 容器网络隔离（需使用宿主机 IP）
• 参数验证错误（N8N 配置问题）
• 防火墙阻止连接

通过正确配置和问题排查，可以顺利部署并使用 Office-Word-MCP-Server，实现 AI 驱动的 Word 文档自动化操作。

---

文档版本: 1.0
创建日期: 2025年12月7日
作者: 基于实际部署经验整理
服务器版本: FastMCP 2.13.3
默认端口: 8000