timeverse-office-doc-mcp

面向 Word / Excel / PowerPoint / PDF 四大格式的全场景读写与分析 MCP Server。提供 74 个工具，覆盖文档创建、内容编辑、格式化、数据分析、模板管理、Session 内存编辑等全链路能力，让 AI 模型直接操控办公文档。

目录

• 工具简介
• 核心特点和优势
• 详细的能力清单
  • Word 工具集（19 个）
  • Excel 工具集（16 个）
  • PowerPoint 工具集（15 个）
  • PDF 工具集（16 个）
  • 跨格式工具集（8 个）
• 架构概览
• 安装方式
  • TimeVerse Studio
  • 其他 AI 客户端
• 使用示例
• 环境变量
• 路径沙箱
• 开发
• License

工具简介

timeverse-office-doc-mcp 是一个基于 Model Context Protocol (MCP) 的办公文档处理服务器。它将 Word、Excel、PowerPoint、PDF 四大主流办公格式的读写、编辑、分析能力封装为 74 个标准化工具，任何支持 MCP 的 AI 客户端都可以直接调用。

无论是让 AI 帮你生成一份格式规范的 Word 报告、处理 Excel 数据统计与排序、制作 PPT 演示文稿，还是对 PDF 进行合并拆分、加水印、提取表格——这个 MCP Server 都能让 AI 直接完成，无需人工切换软件。

一句话定位：让 AI 成为你的全能文档助手。

核心特点和优势

1. 四大格式全覆盖，74 个工具

一个 Server 搞定 Word（19）、Excel（16）、PowerPoint（15）、PDF（16）以及跨格式模板与 Session 管理（8），无需为每种格式单独部署。

2. Session 内存编辑模式

所有编辑类工具均支持 session_id 参数：

• 传入 session_id：文档对象常驻内存，连续编辑零磁盘 IO，完成后一次性保存
• 不传 session_id：走传统的「打开 → 修改 → 保存」流程

对 LLM 完全透明，按需选择，大幅提升多步编辑场景的性能。

3. 模板引擎与变量填充

统一的 {{variable}} 占位符语法，跨 Word / Excel / PPT / PDF 四种格式通用。注册模板时自动扫描提取占位符并推断类型（text / date / number / table / image 等），AI 只需提供变量值即可批量生成文档。

多章节扩页（PPT）：doc_apply_template 支持 sections 参数，自动识别模板中的章节页/内容页原型并复制为每章节一组（封面/目录 + 章节×N + 结尾），一次调用即可生成完整演示文稿；ppt_fill_variables 支持对单页或全文档随时补充变量。占位符即使被 Word/PPT 拆分为多个 run 也能正确替换。

4. 路径沙箱安全机制

• 白名单根目录前缀匹配，子目录自动合法
• 黑名单拦截敏感路径（.ssh、.aws、/etc 等）
• 写操作校验文件扩展名白名单
• 文件大小限制（默认 100MB）
• 相对路径统一锚定到项目根目录（OFFICE_BASE_DIR 可覆盖），不依赖进程 cwd
• 启动时自动将 cwd 加入白名单

5. 文件并发锁

基于 filelock 的文件级锁机制，防止多进程/多请求并发写同一文件导致损坏。所有修改类工具在 handler 调用周期内整体持锁，「读-改-写」全程原子，避免并发读写相互覆盖导致数据丢失。

6. 审计日志

所有工具调用自动记录 JSON Lines 格式审计日志（audit.log），包含工具名、参数摘要、耗时、成功/失败状态，便于追溯与调试。

7. 输入校验

对文件名、Excel 区域引用、表格行列数、文本长度等进行严格校验，防止注入与资源耗尽。

详细的能力清单

Word 工具集（19 个）

文档管理（5 个）

内容编辑（8 个）

格式化与操作（5 个）

分析工具（1 个）

word_get_info(detailed=true) 输出文档结构分析（标题层级、样式分布）；word_extract_text 提取全文并支持大纲模式；分页符通过 word_add_paragraph(page_break=true) 插入。

Excel 工具集（16 个）

工作簿管理（3 个）

数据读写（5 个）

格式化与高级（6 个）

分析工具（2 个）

工作表管理统一由 excel_manage_sheet（add / delete / rename / copy）完成；单元格与行列读写由 excel_read/excel_write/excel_modify_row/excel_modify_column 覆盖；工作簿信息通过 excel_get_overview 获取。

PowerPoint 工具集（15 个）

演示文稿管理（5 个）

内容编辑（8 个）

分析工具（2 个）

演示文稿信息通过 ppt_get_overview 获取；幻灯片删除/移动/复制由 ppt_manage_slide 完成；备注读写由 ppt_slide_notes 覆盖；ppt_get_structure(analyze=true) 输出结构分析（形状/布局分布）；占位符填充由 ppt_fill_variables 按页或全文档完成。

PDF 工具集（16 个）

文档管理（4 个）

内容读取（5 个）

内容写入（4 个）

安全（1 个）

模板工具（2 个）

PDF 加密/解密由 pdf_manage_security（action: encrypt / decrypt）完成；书签通过 pdf_add_annotation(annotation_type="bookmark") 添加；pdf_get_info(analyze=true) 输出文档结构分析；OCR 使用 RapidOCR 引擎（无需系统级依赖）。

跨格式工具集（8 个）

模板管理（4 个）

占位符（1 个）

Session 管理（3 个）

模板注册/删除由 doc_manage_template 完成；Session 内容保存通过 doc_close_session(save=true, output_path=...) 落盘。

架构概览

┌─────────────────────────────────────────────────────────┐
│                    AI 客户端 (MCP Client)                 │
│              TimeVerse Studio / Claude / Cursor ...       │
└────────────────────────┬────────────────────────────────┘
                         │ stdio (JSON-RPC)
┌────────────────────────▼────────────────────────────────┐
│                     MCP Server (stdio)                    │
│  ┌─────────────────────────────────────────────────────┐ │
│  │              server.py — 工具注册与路由               │ │
│  │   TOOL_DEFINITIONS (74 个工具 Schema)                │ │
│  │   TOOL_HANDLERS (工具名 → handler 映射)              │ │
│  └──────────────────────────┬──────────────────────────┘ │
│                             │                             │
│  ┌───────────┬───────────┬──┴────────┬──────────┬──────┐ │
│  │  Word     │  Excel    │  PPT      │  PDF     │ Doc  │ │
│  │  Handler  │  Handler  │  Handler  │  Handler │Handler│ │
│  │  (18)     │  (15)     │  (15)     │  (16)    │ (8)  │ │
│  └─────┬─────└─────┬─────└─────┬─────└─────┬────└──┬───┘ │
│        │           │           │           │       │     │
│  ┌─────▼───────────▼───────────▼───────────▼───────▼───┐ │
│  │                 公共服务层 (common/)                   │ │
│  │  ┌────────────┐ ┌──────────┐ ┌──────────┐           │ │
│  │  │ PathGuard  │ │Validator │ │ErrorHandler│          │ │
│  │  │ 路径沙箱    │ │ 输入校验  │ │ 错误处理   │          │ │
│  │  └────────────┘ └──────────┘ └──────────┘           │ │
│  │  ┌────────────┐ ┌──────────┐ ┌──────────┐           │ │
│  │  │ AuditLog   │ │ FileLock │ │ Session  │           │ │
│  │  │ 审计日志    │ │ 文件锁    │ │ 内存编辑  │          │ │
│  │  └────────────┘ └──────────┘ └──────────┘           │ │
│  │  ┌────────────────────┐                              │ │
│  │  │ TemplateManager    │                              │ │
│  │  │ 模板管理            │                              │ │
│  │  └────────────────────┘                              │ │
│  └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
                         │
          ┌──────────────┼──────────────┐
          ▼              ▼              ▼
    ┌──────────┐  ┌──────────┐  ┌──────────┐
    │ workspace│  │ output   │  │ templates│
    │ 工作目录  │  │ 输出目录  │  │ 模板库    │
    └──────────┘  └──────────┘  └──────────┘

项目结构

timeverse-office-doc-mcp/
├── src/timeverse_office_doc_mcp/
│   ├── __init__.py              # 版本号
│   ├── server.py                # MCP Server 入口（74 个工具定义 + 路由）
│   ├── config.py                # 配置管理（ServerConfig + SecurityConfig）
│   ├── handlers/
│   │   ├── word_handler.py      # Word 19 个工具
│   │   ├── excel_handler.py     # Excel 16 个工具
│   │   ├── ppt_handler.py       # PowerPoint 15 个工具
│   │   ├── pdf_handler.py       # PDF 16 个工具
│   │   └── doc_handler.py       # 跨格式 8 个工具（模板 + Session）
│   └── common/
│       ├── path_guard.py        # 路径沙箱（白名单 + 黑名单 + 扩展名校验）
│       ├── validator.py         # 输入校验（文件名、区域、表格、文本长度）
│       ├── error_handler.py     # 错误处理（ToolError + 装饰器）
│       ├── audit_log.py         # 审计日志（JSON Lines 格式）
│       ├── file_lock.py         # 文件并发锁（filelock 实现）
│       ├── session.py           # Session 内存编辑（TTL 自动清理）
│       └── template_mgr.py      # 模板管理（注册/查找/占位符提取）
├── templates/                   # 文档模板库（registry.json 索引）
├── tests/                       # 测试（6 个文件，覆盖全部 handler）
├── .github/workflows/           # CI/CD（ci.yml + release.yml）
└── pyproject.toml

技术栈

安装方式

TimeVerse Studio

TimeVerse Studio 是本项目的首选 AI 客户端，提供开箱即用的 MCP 集成体验。

方式一：uvx 运行（推荐，无需预装）

在 TimeVerse Studio 的 MCP Server 配置中添加：

{
  "mcpServers": {
    "timeverse-office-doc-mcp": {
      "command": "uvx",
      "args": ["timeverse-office-doc-mcp"],
      "env": {
        "OFFICE_ALLOWED_DIRS": "/path/to/your/documents",
        "OFFICE_BASE_DIR": "/path/to/project/root",
        "OFFICE_TEMPLATES": "/path/to/templates"
      }
    }
  }
}

uvx 会自动创建隔离环境并拉取最新版本，无需手动安装 Python 包。

方式二：直接安装后运行

pip install timeverse-office-doc-mcp

安装后可直接使用 timeverse-office-doc-mcp 命令。在 TimeVerse Studio 中配置：

{
  "mcpServers": {
    "timeverse-office-doc-mcp": {
      "command": "timeverse-office-doc-mcp",
      "env": {
        "OFFICE_ALLOWED_DIRS": "/path/to/your/documents",
        "OFFICE_BASE_DIR": "/path/to/project/root",
        "OFFICE_TEMPLATES": "/path/to/templates"
      }
    }
  }
}

其他 AI 客户端

本项目兼容所有支持 MCP 协议的 AI 客户端，以下以 Claude Desktop 和 Cursor 为例。

Claude Desktop

编辑 Claude Desktop 配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json）：

uvx 方式：

{
  "mcpServers": {
    "timeverse-office-doc-mcp": {
      "command": "uvx",
      "args": ["timeverse-office-doc-mcp"],
      "env": {
        "OFFICE_ALLOWED_DIRS": "/path/to/your/documents"
      }
    }
  }
}

直接安装方式：

{
  "mcpServers": {
    "timeverse-office-doc-mcp": {
      "command": "timeverse-office-doc-mcp",
      "env": {
        "OFFICE_ALLOWED_DIRS": "/path/to/your/documents"
      }
    }
  }
}

Cursor

在 Cursor 设置 → MCP 中添加新的 MCP Server：

uvx 方式：

{
  "mcpServers": {
    "timeverse-office-doc-mcp": {
      "command": "uvx",
      "args": ["timeverse-office-doc-mcp"],
      "env": {
        "OFFICE_ALLOWED_DIRS": "/path/to/your/documents"
      }
    }
  }
}

直接安装方式：

pip install timeverse-office-doc-mcp

然后在 Cursor MCP 配置中填写命令为 timeverse-office-doc-mcp。

从源码安装（开发者）

git clone https://github.com/timeverse/timeverse-office-doc-mcp.git
cd timeverse-office-doc-mcp
pip install -e ".[dev]"

开发模式下可使用以下命令直接启动：

python -m timeverse_office_doc_mcp.server
# 或
timeverse-office-doc-mcp

使用示例

示例 1：创建 Word 报告

对 AI 说：

"帮我创建一份 Word 文档，标题是'2026 年度项目总结'，添加一级标题'项目概述'，下面写一段介绍文字，再添加一个 3 行 2 列的表格，表头是'指标'和'数值'。"

AI 会依次调用：

word_create_document(filename="2026年度项目总结.docx", title="2026 年度项目总结")
word_add_heading(filename="2026年度项目总结.docx", text="项目概述", level=1)
word_add_paragraph(filename="2026年度项目总结.docx", text="本项目旨在...")
word_add_table(filename="2026年度项目总结.docx", rows=3, cols=2, data=[["指标","数值"],["完成度","95%"],["预算执行","88%"]], has_header=true)

创建带封面（居中版式，自动分页）的文档：

word_add_cover(filename="2026年度项目总结.docx", title="2026年度项目总结", subtitle="技术部年度汇报", author="张三", date="2026-08-08", org="某科技有限公司")

示例 2：Session 模式连续编辑

对 AI 说：

"打开 report.docx，先搜索替换把'旧公司名'改成'新公司名'，然后在末尾添加一个分页符，最后保存。"

AI 会使用 Session 模式减少磁盘 IO：

doc_open_session(filename="report.docx", format="word")
  → 返回 session_id: "a1b2c3d4e5f6"

word_search_replace(filename="report.docx", find_text="旧公司名", replace_text="新公司名", session_id="a1b2c3d4e5f6")
word_add_paragraph(filename="report.docx", page_break=true, session_id="a1b2c3d4e5f6")
doc_close_session(session_id="a1b2c3d4e5f6", save=true, output_path="report.docx")

示例 3：Excel 数据分析

对 AI 说：

"读取 sales_data.xlsx 的 Sheet1，分析 A1:D100 区域的数据，然后按'地区'列升序排序，再查找重复的记录。"

AI 会调用：

excel_analyze_data(filename="sales_data.xlsx", sheet="Sheet1", range_str="A1:D100")
excel_sort_data(filename="sales_data.xlsx", sheet="Sheet1", range_str="A1:D100", key_column="地区", ascending=true)
excel_find_duplicates(filename="sales_data.xlsx", sheet="Sheet1", columns=["地区", "产品"])

示例 4：PDF 合并与加水印

对 AI 说：

"把 report1.pdf 和 report2.pdf 合并成一个文件，然后加上'机密'水印。"

AI 会调用：

pdf_merge(files=["report1.pdf", "report2.pdf"], output="merged_report.pdf")
pdf_add_watermark(filename="merged_report.pdf", watermark_text="机密", opacity=0.3, font_size=60, output="merged_report_watermarked.pdf")

示例 5：模板填充生成文档

对 AI 说：

"用'月度报告'模板生成一份文档，变量填充：项目名='Apollo'，日期='2026-08'，负责人='张三'。"

AI 会调用：

doc_apply_template(
    template_name="月度报告",
    output_path="output/Apollo_2026-08.docx",
    variables={"项目名": "Apollo", "日期": "2026-08", "负责人": "张三"}
)

示例 6：PowerPoint 快速制作

对 AI 说：

"创建一个 PPT，第一页标题'产品发布'，添加第二页放一个柱状图，数据是 Q1:100、Q2:150、Q3:200。最后应用蓝色主题。"

AI 会调用：

ppt_create_presentation(filename="产品发布.pptx")
ppt_add_slide(filename="产品发布.pptx", layout=6, title="产品发布")
ppt_add_slide(filename="产品发布.pptx", layout=6, title="季度数据")
ppt_add_chart(
    filename="产品发布.pptx",
    slide_idx=1,
    chart_type="bar",
    data={"categories": ["Q1", "Q2", "Q3"], "series": {"销售额": [100, 150, 200]}},
    title="季度销售趋势"
)
ppt_apply_theme(filename="产品发布.pptx", theme_name="blue")

示例 7：模板多章节生成 PPT 演示文稿

对 AI 说：

"用'银杉新经-商务模板'模板做一份公司介绍 PPT，封面标题'公司介绍'，目录四个章节：公司概况、主营业务、核心优势、联系我们，并给出每个章节的内容要点。"

AI 只需调用一次 doc_apply_template，通过 sections 自动将模板中的章节页/内容页原型复制为每章节一组（封面/目录 + 章节页×4 + 内容页×4 + 结尾页，共 11 页）：

doc_apply_template(
    template_name="银杉新经-商务模板",
    output_path="四川银杉新经科技有限公司-公司介绍.pptx",
    variables={
        "title": "公司介绍", "subtitle": "四川银杉新经科技有限公司",
        "date": "2026-08-08",
        "item1": "公司概况", "item2": "主营业务", "item3": "核心优势", "item4": "联系我们",
        "contact": "四川天府新区华阳街道华府大道一段1号1单元17层11号"
    },
    sections=[
        {"section_no": "01", "section_title": "公司概况", "slide_title": "公司概况",
         "point1": "成立于 2019 年 4 月", "point2": "注册资本 500 万元",
         "point3": "法定代表人刘欢", "point4": "统一社会信用代码 91510100MA66YJJB15"},
        {"section_no": "02", "section_title": "主营业务", "slide_title": "主营业务",
         "point1": "计算机软硬件开发", "point2": "数据处理及存储",
         "point3": "信息系统集成", "point4": "信息技术咨询"},
        {"section_no": "03", "section_title": "核心优势", "slide_title": "核心优势",
         "point1": "信用良好，自身/关联风险均为 0", "point2": "全链条 IT 服务能力",
         "point3": "小微轻量主体，决策灵活", "point4": "业务范围覆盖多元方向"},
        {"section_no": "04", "section_title": "联系我们", "slide_title": "联系我们",
         "point1": "公司全称：四川银杉新经科技有限公司", "point2": "注册地址：四川天府新区",
         "point3": "统一社会信用代码：91510100MA66YJJB15", "point4": "信息来源：国家企业信用信息公示系统"},
    ]
)

生成后如需微调某一页内容，可复制页面后用 ppt_fill_variables 按页补充变量：

ppt_manage_slide(filename="四川银杉新经科技有限公司-公司介绍.pptx", action="copy", slide_idx=7)
ppt_fill_variables(
    filename="四川银杉新经科技有限公司-公司介绍.pptx",
    slide_idx=7,
    variables={"slide_title": "新增章节", "point1": "要点一", "point2": "要点二", "point3": "要点三", "point4": "要点四"}
)

环境变量

本项目设计为零配置开箱即用，以下环境变量均为可选：

为什么不需要配置速率限制、超时、Session TTL 等？

本项目基于 MCP stdio 协议，单客户端顺序通信，天然不存在并发争抢，无需速率限制。 文件大小、表格行列数、文本长度等安全限制已硬编码在代码中，无需用户调整。 Session 过期时间（1 小时）作为内部常量管理，用户无需关心。 未来若增加 HTTP/SSE 多客户端传输，相关配置会随之引入。

路径沙箱

所有文件操作限制在白名单目录内，采用根目录前缀匹配：

• 配置的白名单目录（OFFICE_ALLOWED_DIRS）下的所有子目录/文件自动合法
• workspace、output、templates 三个内置目录自动加入白名单
• 启动时工作目录（cwd）自动加入白名单
• 相对路径统一锚定到项目根目录（OFFICE_BASE_DIR 可覆盖），解析结果可预测，不依赖进程 cwd
• 黑名单拦截敏感路径：.ssh、.aws、.config、.env、AppData、Library、/etc、/sys
• 写操作校验文件扩展名白名单：.docx、.xlsx、.pptx、.pdf
• 白名单之外一律拒绝

开发

# 安装开发依赖
pip install -e ".[dev]"

# 代码检查
ruff check src/ tests/
ruff format src/ tests/
mypy src/

# 运行测试
pytest -v

CI/CD

• ci.yml：push/PR 到 main 时触发，lint（ruff + mypy）+ 矩阵测试（Ubuntu/macOS/Windows × Python 3.10/3.11/3.12）
• release.yml：打 v* tag 时触发，自动构建并发布到 PyPI

License

MIT