# office2pdf-mcp

**English abstract:** A macOS-only MCP server that converts DOCX/DOC and PPT/PPTX files to PDF using the native Microsoft Word / PowerPoint rendering engine via AppleScript. Every conversion runs on a uniquely named temporary copy inside the Office sandbox container, so documents you already have open are never closed, modified, or saved. Fonts, pagination and layout match what you see in Office.

[English abstract](#english-abstract) · 中文

---

macOS 上的 MCP 服务器：调用本机 Microsoft Word / PowerPoint，把 DOCX/DOC、PPT/PPTX 转换为 PDF。使用 Office 原生渲染，字体、分页、图表位置与在 Office 中打开时一致（LibreOffice 等替代渲染常有差异）。

> **安全承诺（0.2.0 起）**：转换只操作 Office 沙盒容器内的临时副本，**绝不会关闭、修改或保存你正在编辑的 Word / PowerPoint 文档**。旧版曾在转换前执行 `close document 1 saving no` 清空所有已打开文档，该行为已彻底移除。

## 功能

| 工具 | 说明 |
|------|------|
| `convert_docx_to_pdf` | 单个 `.docx` / `.doc` → PDF（Word 渲染） |
| `convert_docx_directory` | 批量转换目录下所有 DOCX（可选递归、输出目录、进度上报） |
| `convert_ppt_to_pdf` | 单个 `.ppt` / `.pptx` → PDF（PowerPoint 渲染） |
| `convert_ppt_directory` | 批量转换目录下所有 PPT/PPTX（可选递归、输出目录、进度上报） |

- 自动处理 macOS 沙盒 / Powerbox 权限，无需逐文件手动授权。
- 源文件始终先复制到 Office 沙盒容器，转换结束自动清理临时副本。
- 输出路径落在受限目录时，也会先写容器、成功后再复制回目标路径。
- 批量转换串行执行（Office AppleScript 不适合并发）。

## 环境要求

- **macOS**（依赖 AppleScript 控制 Office，不支持 Windows / Linux）
- **Microsoft Word** 与 / 或 **Microsoft PowerPoint** 桌面版（Microsoft 365 或 2016+）
- **Python ≥ 3.10**
- **[uv](https://github.com/astral-sh/uv)**（推荐；也可用普通 pip 安装）

## 安装与运行

### 从源码运行

```bash
git clone https://github.com/NatsUIJM/office2pdf-mcp.git
cd office2pdf-mcp
uv run -m office2pdf_mcp.server
```

### 从 Git 直接运行（uvx）

```bash
uvx --from git+https://github.com/NatsUIJM/office2pdf-mcp office2pdf-mcp
```

### MCP 客户端配置

Claude Desktop、Cherry Studio 等支持 stdio MCP 的客户端，配置示例：

```json
{
  "mcpServers": {
    "office2pdf": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/office2pdf-mcp",
        "run",
        "-m",
        "office2pdf_mcp.server"
      ]
    }
  }
}
```

使用 `uvx` 时：

```json
{
  "mcpServers": {
    "office2pdf": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/NatsUIJM/office2pdf-mcp",
        "office2pdf-mcp"
      ]
    }
  }
}
```

## 工具参数

```text
convert_docx_to_pdf(docx_path, output_path="", timeout=120)
convert_docx_directory(input_dir, output_dir="", recursive=False, timeout=120)
convert_ppt_to_pdf(ppt_path, output_path="", timeout=120)
convert_ppt_directory(input_dir, output_dir="", recursive=False, timeout=120)
```

- `output_path` 留空时输出到源文件同目录同名 `.pdf`。
- `timeout` 是单文件转换的子进程超时秒数；Office 冷启动较慢时可调大。
- 目录工具返回 `{total, success, failed, results}`，并支持 MCP 进度上报。

## 工作原理

Word / PowerPoint 是 macOS 沙盒应用，访问自身容器外的文件会触发 Powerbox「授予文件访问权限」对话框；该对话框无法用 AppleScript 自动化，且会逐次堆积。本服务器的处理方式：

1. 把源文件复制到 Office 自身沙盒容器的暂存目录：
   - `~/Library/Containers/com.microsoft.Word/Data/Documents/_office2pdf_stage/`
   - `~/Library/Containers/com.microsoft.Powerpoint/Data/Documents/_office2pdf_stage/`
2. 用唯一文件名（`_conv_<随机串>_原文件名`）打开副本。
3. 校验 `name of active document` 确实是本次副本；如果不是，立即报错退出，不保存任何内容。
4. 执行 `save as ... file format format PDF`，随后只关闭这一个副本。
5. 删除临时副本；若目标 PDF 位于受限目录，先写容器再复制回目标路径。

由于源文件始终是副本，转换过程不会触碰用户已打开的文档，也不会修改源文件。

## 权限

首次由某个宿主应用（终端、Cherry Studio、Claude Desktop 等）调用时，macOS 会请求「自动化」权限：

- 系统设置 → 隐私与安全性 → 自动化 → 允许该应用控制 **Microsoft Word** / **Microsoft PowerPoint**。
- 若出现「授予文件访问权限」对话框，说明 Office 正在访问容器外路径；本服务器正常路径不会触发，遇到时请检查是否堆积了旧对话框。

## 已知限制

- 仅支持 macOS 与桌面版 Microsoft Office；不支持 LibreOffice、WPS 或云端转换。
- 转换期间会短暂激活 Word / PowerPoint（AppleScript 限制），可能抢占前台焦点。
- 批量转换串行执行；大量文件时耗时与文件数线性相关。
- 依赖 Office 的 AppleScript 字典，未来 Office 大版本升级可能影响兼容性。

## 测试

```bash
uv run python test_pathlogic.py
```

`test_pathlogic.py` 覆盖路径判定、AppleScript 生成（含“不得清空已打开文档”的回归检查）与沙盒暂存逻辑，不需要真实 Office 文档。端到端转换需要本机安装 Office 并准备样本文档，按上面的工具参数直接调用即可。

## 目录结构

```text
office2pdf-mcp/
├── office2pdf_mcp/
│   ├── __init__.py
│   └── server.py        # MCP 服务器与 AppleScript 实现
├── test_pathlogic.py    # 无需 Office 的逻辑/回归测试
├── pyproject.toml
├── uv.lock
└── LICENSE
```

## English abstract

A macOS-only MCP server that converts DOCX/DOC and PPT/PPTX to PDF through the native Microsoft Word / PowerPoint rendering engine. Conversions run on uniquely named temporary copies inside the Office sandbox container; the server verifies the active document before saving and closes only that copy, so user documents are never touched. Batch conversion, recursive directory scanning and MCP progress reporting are supported.

## License

[MIT](LICENSE)