Document Operator

License: MIT Python MCP

一个 MCP (Model Context Protocol) Server，让 AI 助手（Claude Desktop、Trae、Cursor 等）能够通过自然语言操作 Word(.docx) 和 Excel(.xlsx) 文档。

---

功能

类别	操作	说明
Word	📖 读取全文 / 指定段落	支持查看文档结构（标题、段落、表格）
	📊 提取表格	提取所有表格数据
	✏️ 修改段落	修改、追加、插入段落
	🔍 搜索替换	全文搜索并替换文本
Excel	📖 读取数据	读取 Sheet、单元格、区域
	✏️ 写入单元格	按地址或行列号写入
	🗂️ 管理 Sheet	添加、删除、列出 Sheet
	📝 创建文件	创建新的 xlsx 文件
临时表	📊 批量查询	按指定Sheet/行/列批量提取数据
	💾 内存暂存	将查询结果存入命名临时表
	📤 导出保存	将临时表保存为 .xlsx 文件

---

快速开始

1. 安装

# 方式一：pip 安装
pip install git+https://github.com/dai-zw/document-operator-mcp.git

# 方式二：uvx（推荐）
uvx --from git+https://github.com/dai-zw/document-operator-mcp.git document-operator-mcp

2. 配置到 AI 客户端

Claude Desktop

{
  "mcpServers": {
    "document-operator": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/dai-zw/document-operator-mcp.git", "document-operator-mcp"]
    }
  }
}

Trae IDE / Cursor

在项目的 .trae/mcp.json 或 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "document-operator": {
      "command": "python",
      "args": ["-m", "document_operator_mcp.server"]
    }
  }
}

或直接指定路径：

{
  "mcpServers": {
    "document-operator": {
      "command": "python",
      "args": [".trae/skills/document-operator/mcp_server/server.py"]
    }
  }
}

3. 开始对话

配置完成后，在 AI 对话中可以直接说：

• "读取这份 word 文档 d:/report.docx"
• "把第3段改成：项目已完成"
• "在 excel 的 B2 填入 500"
• "列出这个表格有哪些 sheet"
• "把文档里所有的'旧系统'替换成'新平台'"
• "从 data.xlsx 的 Sheet1 读取第2-50行的 A、C、F 列，存为临时表 tb1，然后保存到 extract.xlsx"

AI 会自动调用对应的 MCP Tool 完成操作。

---

本地开发

# 克隆项目
git clone https://github.com/dai-zw/document-operator-mcp.git
cd document-operator-mcp

# 安装依赖
pip install -e .

# 启动 MCP Server（stdio 模式）
python -m document_operator_mcp.server

# 用 MCP Inspector 调试
mcp dev document_operator_mcp/server.py

---

提供的 Tool 列表（14 个）

Word 工具

Tool	用途
read_docx	读取全文或指定段落
read_docx_tables	提取所有表格
write_docx	修改 / 追加 / 插入段落
replace_docx_text	全文搜索替换
get_docx_info	查看文档结构

Excel 工具

Tool	用途
read_xlsx	读取 Sheet / 单元格 / 区域
write_xlsx	写入单元格
list_xlsx_sheets	列出所有 Sheet
create_xlsx	创建新工作簿
manage_xlsx_sheet	添加或删除 Sheet

临时表 / 批量查询工具

Tool	用途
query_xlsx	从 Excel 批量读取指定Sheet/行/列，可选存入内存临时表
get_temp_table	查看内存临时表数据
save_temp_table	将临时表保存为 .xlsx 文件
list_temp_tables	列出当前会话所有临时表

批量查询典型工作流：

query_xlsx("data.xlsx", sheet_name="Sheet1", start_row=2, end_row=100, columns="A,C,F", output_table_name="mydata")
get_temp_table("mydata")                                    # 查看数据
save_temp_table("mydata", "output.xlsx")                    # 保存为新文件

---

技术栈

• python-docx - Word .docx 操作
• openpyxl - Excel .xlsx 操作
• MCP Python SDK - MCP 协议实现

限制

• Word 仅支持 .docx 格式，不支持旧版 .doc
• Excel 仅支持 .xlsx 格式
• Word "分页" 操作为段落级近似（python-docx 不支持原生页码）
• 修改操作会直接保存到原文件，请注意备份

License

MIT