Skip to main content
Glama
Sign In
ppt-mcp

ppt-mcp

by ZiChuanLan
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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 协议适配和工具封装

  • 两者不是两套重复系统，而是主服务与接入层关系

Related MCP server: mcp-ToseaAI

适合什么场景

  • 想让 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/：

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.

Available Tools

16 tools
ppt_cancel_jobB

Cancel a pending or running conversion job.

Inputs: job_id (required). Returns: object

ppt_check_ai_ocrC

Probe whether a model can work on the current AI OCR chain.

Inputs: model (required), api_key (required), options, base_url, +2 more. Returns: object

ppt_check_routeA

Lock a high-level route workflow after the user explicitly confirms it.

This is step 1 of the high-level guided flow. It only locks the route and returns a route_workflow_id. Then use ppt_set_conversion_target, ppt_list_route_models if needed, ppt_set_route_options, and finally ppt_convert_pdf.

Inputs: route (required), route_confirmed. Returns: object

ppt_convert_pdfC

Submit the locked high-level workflow after target and options are ready.

Inputs: route_workflow_id (required), retain_process_artifacts. Returns: object

ppt_create_jobA

Create a PDF-to-PPT conversion job from a local pdf_path.

The PDF is read from local disk by this MCP server, then uploaded to the running ppt API. This is the low-level escape hatch. For normal use prefer ppt_list_routes -> ppt_check_route -> ppt_set_conversion_target -> ppt_list_route_models (if needed) -> ppt_set_route_options -> ppt_convert_pdf.

Never use this tool unless the user explicitly asks to bypass the guided route workflow and confirms low_level_override_confirmed=true. The pdf_path must be a real existing local PDF path explicitly provided by the user.

Inputs: pdf_path (required), options, low_level_override_confirmed. Returns: object

ppt_download_artifactC

Download a retained artifact file to a local output path.

Inputs: job_id (required), artifact_path (required), output_path. Returns: object

ppt_download_resultC

Download the completed PPTX result to a local output path.

Inputs: job_id (required), output_path. Returns: object

ppt_get_job_artifactsB

Return debug/process artifact metadata for a job.

Inputs: job_id (required). Returns: object

ppt_get_job_statusA

Get the current status, stage, progress, and errors for a job.

Inputs: job_id (required). Returns: object

ppt_health_checkB

Check whether the wrapped local ppt API is reachable.

Inputs: no named parameters. Returns: object

ppt_list_ai_modelsA

Low-level raw model discovery. Prefer ppt_list_route_models in normal OCR flows.

Only repeat the exact returned model IDs to the user. Do not invent provider categories, unofficial aliases, or recommendations.

Inputs: api_key (required), provider (required), base_url, capability. Returns: object

ppt_list_jobsB

List recent conversion jobs from the wrapped local ppt API.

Inputs: limit. Returns: object

ppt_list_route_modelsA

List candidate models for the currently locked high-level route workflow.

Only use this after pdf_path and page range are already confirmed on the same route_workflow_id.

Inputs: route_workflow_id (required). Returns: object

ppt_list_routesA

List human-friendly routes for the user to choose from.

Do not choose, infer, or recommend a route on the user's behalf. The next step is to ask the user to pick one route, then call ppt_check_route with that route and route_confirmed=true.

Inputs: no named parameters. Returns: object

ppt_set_conversion_targetA

Write pdf_path and page range decisions into a locked route workflow.

This is step 2 of the high-level guided flow. Use it to persist conversion target state so weaker models do not have to remember page ranges from chat history. pdf_path must be a real local PDF path explicitly provided by the user. Do not treat the page scope as complete until page_range_confirmed=true is explicitly written for the currently selected pages.

Inputs: route_workflow_id (required), page_end, pdf_path, page_start, +2 more. Returns: object

ppt_set_route_optionsA

Write scanned-page, footer, and AI model decisions into the workflow.

This is step 3 of the high-level guided flow. Use ppt_list_route_models first when the user wants to select a non-default AI OCR model. Do not use this tool before pdf_path and page range are confirmed.

Inputs: route_workflow_id (required), ocr_ai_model, scanned_page_mode, ocr_ai_model_decision, +2 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.4/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, but ppt_list_route_models and ppt_list_ai_models overlap conceptually, and ppt_check_route vs ppt_create_job may be confused as both initiate workflows. However, descriptions clearly differentiate high-level guided flow from low-level escape hatch, reducing real ambiguity.

    Naming Consistency5/5

    All tools share a consistent 'ppt_verb_noun' snake_case pattern, with clear action-object pairs. Verbs are consistent (list, get, set, create, download, check) and objects are specific, making the naming predictable and readable.

    Tool Count4/5

    16 tools is slightly above the ideal 3-15 range, but each tool maps to a distinct step in either the high-level guided workflow or low-level job management. The two parallel flows justify the count, making it reasonable.

    Completeness5/5

    The tool surface covers the full lifecycle: route selection, workflow state management, job creation, status tracking, cancellation, and result/artifact download. Both high-level and low-level paths are represented, leaving no critical gaps for the PDF-to-PPT conversion domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers