ppt-mcp

PDF2PPT 主服务的 MCP 接入层。

ppt-mcp 不重新实现 PDF 解析、OCR 或 PPT 生成。
它做的事情是把现有 PDF2PPT API 包装成 MCP tools，让 Claude Desktop、Cursor、Codex CLI 等客户端可以直接调用转换能力。

它和主服务是什么关系

一句话理解：

MCP Client -> ppt-mcp -> PDF2PPT API -> worker

职责边界：

• PDF2PPT 主服务负责 PDF 解析、OCR、任务调度和 PPT 生成
• ppt-mcp 负责 MCP 协议适配和工具封装
• 两者不是两套重复系统，而是主服务与接入层关系

适合什么场景

• 想让 AI 客户端直接调用 PDF 转 PPT，而不是手动打开 Web 页面
• 想把“上传 PDF -> 创建任务 -> 轮询状态 -> 下载结果”封装成 MCP tools
• 想把现有 PDF2PPT 服务接入本地 Agent 或自动化工作流

推荐使用方式

1. 本地 stdio MCP，最简单也最稳

这是默认推荐模式。

• PDF2PPT 服务跑在本机
• ppt-mcp 也跑在本机
• transport 使用 stdio
• PPT_API_BASE_URL 指向 http://127.0.0.1:8000

这时：

• 浏览器用户走 Web 页面
• MCP 用户走本地 API
• 两条链路互不干扰

2. 本地 stdio MCP，连接远程 PDF2PPT

适合：

• AI 客户端在本机
• 但转换服务部署在远程服务器

这时：

• PPT_API_BASE_URL 指向远程服务根地址
• ppt-mcp 仍然在本机运行
• 本地 PDF 由 ppt-mcp 读取后上传到远程 API

3. 远程 ppt-mcp-remote

适合：

• 团队共用
• 需要统一 MCP 入口
• 需要 Streamable HTTP MCP

但复杂度更高：

• 需要入口认证
• 需要处理上传源文件
• 需要考虑下载、权限和公网暴露

如果只是本机自用，优先使用第 1 种。

快速开始

1. 先启动主服务

cd /home/lan/workspace/ppt
docker compose up -d --build api worker redis

默认情况下，ppt-mcp 会连接：

• http://127.0.0.1:8000

2. 安装

cd /home/lan/workspace/ppt-mcp
uv sync

3. 运行本地 stdio MCP

cd /home/lan/workspace/ppt-mcp
uv run ppt-mcp

4. 最少环境变量

cp .env.example .env

最少需要：

PPT_API_BASE_URL=http://127.0.0.1:8000
PPT_API_TIMEOUT_SECONDS=120

高层 route workflow 默认还会写本地状态到：

var/route-workflows

这让 ppt_check_route -> ppt_set_conversion_target -> ppt_list_route_models -> ppt_set_route_options -> ppt_convert_pdf 这一串高层工具在 MCP 宿主进程重启后，仍可以继续沿用同一个 route_workflow_id。默认 TTL 是 3600 秒，超过后仍会要求从 ppt_check_route 重新开始。

如果主服务开启了：

API_BEARER_TOKEN=your-shared-secret

那么这里也要配置：

PPT_API_BEARER_TOKEN=your-shared-secret

关键配置

PPT_API_BASE_URL 应该怎么写

它应该指向 PDF2PPT 服务根地址，而不是 /api/v1。

正确示例：

PPT_API_BASE_URL=http://127.0.0.1:8000

或者：

PPT_API_BASE_URL=https://ppt.example.com

不建议写成：

PPT_API_BASE_URL=http://127.0.0.1:8000/api/v1

也不建议默认写成 Web 入口：

PPT_API_BASE_URL=http://127.0.0.1:3000

因为 3000 这条链路通常会受到 WEB_ACCESS_PASSWORD 影响。

Bearer Token 的对应关系

• API_BEARER_TOKEN 是主服务 API 要求的密码
• PPT_API_BEARER_TOKEN 是 ppt-mcp 请求 API 时带上的密码

通常这两个值应保持一致。

高层 route workflow 本地持久化

当前高层 route workflow 不再只保存在进程内存。

• 每次 ppt_check_route 创建 workflow 后，会把状态写到本地目录
• 后续 ppt_set_conversion_target、ppt_list_route_models、ppt_set_route_options 更新后也会同步写回
• 如果 MCP 宿主只是重启进程，但仍在同一台机器、同一份存储目录上运行，原来的 route_workflow_id 仍可恢复
• 如果 workflow 超过 TTL，或者持久化文件损坏 / 被删除，仍会返回“请从 ppt_check_route 重新开始”

相关环境变量：

• PPT_MCP_ROUTE_WORKFLOW_STORE_DIR 默认值是仓库内的 var/route-workflows
• PPT_MCP_ROUTE_WORKFLOW_TTL_SECONDS 默认值是 3600

示例：

PPT_MCP_ROUTE_WORKFLOW_STORE_DIR=/home/lan/workspace/ppt-mcp/var/route-workflows
PPT_MCP_ROUTE_WORKFLOW_TTL_SECONDS=3600

这两个变量只影响高层 route workflow 的本地恢复，不影响远程 ppt-mcp-remote 的上传源缓存目录 PPT_MCP_DATA_DIR。

当前工具能力

ppt-mcp 已覆盖主服务的常见任务流，包括：

• 路线查询与确认
• 创建任务
• 查询任务状态
• 列出任务
• 取消任务
• 下载结果
• 读取产物
• 列出模型
• 检查 AI OCR 路线

从使用方式上，更推荐优先走高层 route workflow，而不是一开始就手填所有底层字段。

路径兼容性

本地 stdio 模式下，ppt-mcp 现在会转换常见路径格式：

• Windows 路径，例如 C:\Users\...\file.pdf
• \\wsl.localhost\发行版名\... 路径

这使得 MCP 客户端在 Windows / WSL 混合环境下更容易把本地 PDF 路径传给 ppt-mcp。

文档

更详细的说明已拆到 docs/：

• 文档首页
• 快速开始
• 使用模式与部署建议
• 配置说明
• Remote MCP PRD
• Remote MCP Tool Contracts

MCP 配置示例

本地 clone 方式：

{
  "mcpServers": {
    "ppt": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/lan/workspace/ppt-mcp",
        "run",
        "ppt-mcp"
      ],
      "env": {
        "PPT_API_BASE_URL": "http://127.0.0.1:8000"
      }
    }
  }
}

远程：

{
  "ppt": {
    "type": "stdio",
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/ZiChuanLan/ppt-mcp",
      "ppt-mcp"
    ],
    "env": {
      "PPT_API_BASE_URL": "https://ppt.015201314.xyz",
      "MINERU_API_TOKEN": "yourkey",
      "SILICONFLOW_API_KEY": "sk-yourkey"
    }
  }
}

License

MIT.