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 sync3. 运行本地 stdio MCP
cd /home/lan/workspace/ppt-mcp
uv run ppt-mcp4. 最少环境变量
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/：
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"
}
}
}
}远程： ``json { "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.
