WPS Office MCP 连接包

通过 MCP 协议（Model Context Protocol）实现 AI 助手与 WPS Office 的集成，支持对 WPS 文字（Writer）、表格（ET）、演示（WPP）的自动化操作。

MCP Server 安装时从 GitHub lc2panda/wps-skills 自动克隆并编译，提供 231+ 个工具。

---

架构说明

AI 助手 (Claude Code / Cursor / WorkBuddy / 等)
    │
    │  MCP 协议 (stdio)
    ▼
┌──────────────────────────────────┐
│  wps-mcp-server (node 子进程)     │
│  安装时 git clone + npm build     │
│  ┌────────────────────────────┐  │
│  │  wps-mcp-addon (WPS 加载项) │  │
│  └────────────────────────────┘  │
└──────────────┬───────────────────┘
               │ PowerShell COM 自动化
               ▼
┌──────────────────────────────────┐
│  WPS Office 进程                  │
│  (Writer / ET / WPP)             │
└──────────────────────────────────┘

关键组件：

1. wps-mcp-server — MCP 协议服务端，从 GitHub 自动克隆并编译为 dist/index.js
2. wps-mcp-addon (WPS 加载项) — 安装在 WPS jsaddons 目录中的 JS 插件，提供 COM 通信通道
3. PowerShell COM 桥接 — 通过 WPS COM 接口自动化操作 WPS Office

---

文件结构

wps-office-mcp/
├── README.md                   ← 本文件：安装使用说明
├── package.json                ← npm 脚本入口
├── install-wps-mcp.ps1         ← 一键安装/卸载脚本
├── start-wps-mcp-server.ps1    ← MCP Server 启动脚本（前台/后台/停止）
└── wps-addin/                  ← WPS 加载项文件（wps-mcp-addon）
    ├── manifest.xml            ← 加载项注册清单（wps/et/wpp 三端注册）
    ├── ribbon.xml              ← WPS 功能区按钮布局
    ├── index.html              ← 加载项入口页面
    └── js/
        └── main.js             ← 核心脚本（COM 桥接模式）

注意：wps-mcp-server/ 目录不在包中，执行 -InstallServer 时从 GitHub 自动克隆。

---

快速开始

前置依赖

软件	版本要求	用途
WPS Office	2019+ / 个人版 / 专业版	办公软件
Node.js	>= 18.0.0	编译 MCP Server
Git	任何版本	从 GitHub 克隆代码
PowerShell	Windows 自带	安装脚本和 COM 桥接

一键安装

以 管理员身份 打开 PowerShell，执行：

cd <本包目录>

# 安装全部组件（WPS 加载项 + 从 GitHub 下载并编译 MCP Server）
.\install-wps-mcp.ps1 -Action Install -InstallServer

或使用 npm 脚本：

npm run install:all

执行过程：

1. 关闭所有 WPS 进程
2. 将 wps-addin/ 复制到 %APPDATA%\Kingsoft\WPS\jsaddons\wps-mcp-addon_\
3. 更新 publish.xml 注册加载项
4. 更新 authaddin.json 配置 wps/et/wpp 三端
5. git clone --depth 1 下载 MCP Server 源码
6. npm install && npm run build 编译
7. 已有克隆时自动 git pull 更新

仅安装 WPS 加载项（手动）

1. 关闭所有 WPS Office 程序（Writer、ET、WPP 全部关闭）

2. 将 wps-addin/ 文件夹复制到 WPS 加载项目录：

   %APPDATA%\Kingsoft\WPS\jsaddons\wps-mcp-addon_\
   

3. 编辑 %APPDATA%\Kingsoft\WPS\jsaddons\publish.xml，添加：

   <jsplugin name="wps-mcp-addon" type="wps,et,wpp" url="wps-mcp-addon_/" enable="enable_dev"/>
   

启动 MCP Server

stdio 模式（默认，MCP 客户端直接启动子进程）：

.\start-wps-mcp-server.ps1               # 前台运行（测试用，Ctrl+C 停止）
.\start-wps-mcp-server.ps1 -Mode background  # 后台运行
.\start-wps-mcp-server.ps1 -Stop            # 停止后台进程

HTTP SSE 模式（独立 HTTP 服务，WorkBuddy 通过端口连接）：

.\start-wps-mcp-server.ps1 -HTTP                        # 前台，端口 18000
.\start-wps-mcp-server.ps1 -HTTP -Mode background        # 后台
.\start-wps-mcp-server.ps1 -HTTP -Mode background -Port 8080  # 自定义端口

HTTP 模式启动后，WorkBuddy 通过 http://localhost:18000/sse 连接。 首次启动会自动安装依赖（express, cors, @modelcontextprotocol/sdk）。

启动 WPS Office

1. 打开 WPS Office（推荐先打开 WPS Writer）
2. 检查功能区顶部是否出现 "MCP助手" 选项卡
3. 点击 → "连接状态" 按钮，确认初始化成功
4. 如果看不到该选项卡，请重启 WPS Office

配置到 AI 工具

提供两种连接方式：

stdio 模式（默认，通用）

在 AI 工具配置文件中添加：

{
  "mcpServers": {
    "wps-office": {
      "command": "node",
      "args": ["<本包绝对路径>/wps-mcp-server/wps-office-mcp/dist/index.js"]
    }
  }
}

HTTP SSE 模式（独立 HTTP 服务）

先启动 HTTP 服务：.\start-wps-mcp-server.ps1 -HTTP -Mode background

然后在 AI 工具中配置：

{
  "mcpServers": {
    "wps-office": {
      "url": "http://localhost:18000/sse",
      "transport": "http"
    }
  }
}

配置文件位置：

客户端	配置文件
WorkBuddy	~/.workbuddy/mcp.json
Claude Code	~/.claude/settings.json
Cursor	项目根目录 .cursor/mcp.json
Codex CLI	~/.codex/config.toml
其他	参考各工具文档

---

卸载

# 卸载 WPS 加载项
.\install-wps-mcp.ps1 -Action Delete

# 卸载加载项 + 删除 MCP Server 目录
.\install-wps-mcp.ps1 -Action Delete -InstallServer

# 静默卸载
.\install-wps-mcp.ps1 -Action Delete -Force

---

使用说明

基本功能

功能	说明
新建文档	在 WPS 中创建空白 Word/Excel/PPT
插入文本	在光标处或指定位置写入内容
读取文档	获取当前文档的标题、内容、字数等
另存为	保存文档到指定路径
查找替换	在文档中搜索并替换文本
设置格式	调整字体、颜色、段落等样式
插入表格/图片	在文档中插入表格和图片
插入页眉/页脚	添加文档页眉页脚

高级功能（231+ 工具）

应用	工具数	主要能力
Excel	82	公式、图表、透视表、数据验证、条件格式、宏
Word	32	模板填写、批注、书签、目录生成、修订
PPT	112+	动画、3D、母版、形状、数据可视化、幻灯片
通用	9+	保存、格式转换、连接检测

常用命令示例

"在 WPS 中新建一个空白文档"
"在当前文档中插入文字：xxxx"
"保存文档到桌面，文件名：xxx.docx"
"把文档中所有的 'abc' 替换为 'xyz'"
"读取当前文档内容"
"插入一个 3x5 的表格"

---

脚本命令速查

# 安装全部
.\install-wps-mcp.ps1 -Action Install -InstallServer

# 仅安装加载项
.\install-wps-mcp.ps1 -Action Install

# 自定义加载项名称
.\install-wps-mcp.ps1 -Action Install -AddonName "my-addon"

# 指定源文件夹
.\install-wps-mcp.ps1 -Action Install -SourcePath "D:\my-addon"

# 卸载
.\install-wps-mcp.ps1 -Action Delete [-Force]

# 启动 MCP Server（前台）
.\start-wps-mcp-server.ps1

# 启动 MCP Server（后台）
.\start-wps-mcp-server.ps1 -Mode background

# 停止后台 MCP Server
.\start-wps-mcp-server.ps1 -Stop

# 启动 HTTP SSE 服务（前台）
.\start-wps-mcp-server.ps1 -HTTP

# 启动 HTTP SSE 服务（后台，自定义端口）
.\start-wps-mcp-server.ps1 -HTTP -Mode background -Port 8080

# npm 快捷方式
npm run install:all        # 安装全部
npm run install:addon      # 仅安装加载项
npm run install:server     # 仅编译 MCP Server（stdio）
npm run start:http         # 启动 HTTP SSE 桥接服务

---

故障排查

问题	原因	解决方法
WPS 未响应	WPS 未运行	打开 WPS Writer/ET/WPP
"PowerShell COM 调用失败"	COM 注册未就绪	以管理员身份运行 WPS 一次
看不到 "MCP助手" 选项卡	加载项未正确安装	确认 publish.xml 配置正确，重启 WPS
操作无响应	文档未打开	确保 WPS 中已打开一个文档
权限错误	PowerShell 执行策略限制	运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
stdio MCP 无法启动	未安装 MCP Server	运行 .\install-wps-mcp.ps1 -Action Install -InstallServer
git clone 失败	无 Git 环境	安装 Git：https://git-scm.com
编译失败	Node.js 版本过低	升级到 Node.js >= 18.0.0
HTTP 模式端口被占用	已有进程占用端口	使用 -Port 指定其他端口，或先停止占用进程
HTTP 桥接依赖安装失败	网络问题	手动执行 npm install
PowerShell 脚本被禁止	执行策略限制	运行 Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

---

技术细节

项目	说明
通信协议	MCP over stdio / MCP over HTTP SSE
HTTP 端口	18000（可通过 -Port 参数自定义）
WPS 控制方式	PowerShell COM 自动化
WPS 加载项	JS 插件模式，WPS 原生加载项 API
MCP Server 技术栈	TypeScript + @modelcontextprotocol/sdk + winston
HTTP 桥接技术栈	Node.js + Express + @modelcontextprotocol/sdk
工具数量	231+（持续增长）
支持版本	WPS Office 2019+ / 个人版 / 专业版
许可证	MIT

组件来源

组件	来源	方式
WPS 加载项 (wps-addin)	基于 lc2panda/wps-skills 的 wps-claude-addon (MIT) 修改	内置
MCP Server	lc2panda/wps-skills (MIT)	安装时 git clone
HTTP 桥接 (http-bridge-server.js)	本包内部	内置，首次启动时自动 npm install 依赖
COM 桥接脚本	wps-skills 内置	含在克隆代码中

版权声明：本项目遵循 MIT License。WPS 加载项 (wps-addin/) 基于 lc2panda/wps-skills 的原始代码修改，原始版权归 lc2panda 所有。

---

更新日志

• 2026-07-04：初始版本，含 WPS 加载项 + GitHub 自动下载 MCP Server + 启动脚本