duanqiaocxu/ppt-mcp-server 安装教程：把 PPT 大纲生成接口接进 Chatbox 流程

打开 duanqiaocxu/ppt-mcp-server 之前，最好先放下一个预期：它当前不是一套已经打包好的标准 MCP 服务，而是一份写在 PPTMCP.txt 里的 FastAPI 接口草稿。仓库没有现成的 server.py、requirements.txt、.env 文件，安装动作其实是先把文本里的代码拆出来，跑起 /generate-ppt，再让 Chatbox 通过 HTTP 请求拿到 ppt_markdown。这类项目最容易误会的地方不在命令多，而在入口太“半成品”：你按 MCP 客户端配置去找，会找偏；你按普通 Python 服务去还原，反而顺很多。

先把项目定位说清楚

这个仓库名字叫 ppt-mcp-server，但从当前文件内容看，它不是那种写进 Claude Desktop mcpServers 配置后走 stdio 的 MCP 服务。它提供的是一个 FastAPI HTTP 服务，核心接口是 POST /generate-ppt。

调用时传入三个字段：topic、audience、slides。服务会把这些参数拼进提示词，让模型生成一份 PPT 提纲和每页内容，并按 Markdown / Marp 风格用 --- 分隔页面。返回字段叫 ppt_markdown。

所以更准确的使用方式是：把它当成“PPT 内容生成 HTTP 服务”，再在 Chatbox、自动化流程、低代码工具或自己的前端里通过 HTTP 请求调用。这个边界很重要，不然你会一直找不存在的 MCP 配置文件。

安装前准备

当前仓库没有标准 README，也没有拆好的 Python 项目目录。开始之前，建议先准备这些：

• Python 3.10 或更新版本。
• 一个可用的 OpenAI API Key。
• 能访问本机 8000 端口的浏览器或 Chatbox。
• 如果要把 Markdown 真正导成 PPTX，再准备 Marp CLI 或其他 Markdown 转幻灯片工具。

这里我建议单独建一个干净目录，不要直接在下载下来的仓库根目录里乱放一堆测试文件。这个仓库本身只有文本说明，目录干净一点，后面排查会省心。

把 PPTMCP.txt 还原成项目结构

先 clone 仓库：

git clone https://github.com/duanqiaocxu/ppt-mcp-server.git
cd ppt-mcp-server

截至我这次实测，仓库里只有 PPTMCP.txt。所以需要手动创建真正运行用的目录：

mkdir ppt_mcp_server
cd ppt_mcp_server
touch server.py requirements.txt .env

推荐目录保持这样：

ppt_mcp_server/
├── server.py
├── requirements.txt
└── .env

这个步骤别跳。很多人看到 GitHub 项目名就以为 clone 完能直接跑，结果终端里输入 uvicorn server:app 才发现根本没有 server.py。我当时也愣了一下，才意识到它是“说明文件里贴代码”的形式。

安装 Python 依赖

先建虚拟环境。macOS 或 Linux 可以这样：

python3 -m venv .venv
source .venv/bin/activate

Windows 可以这样：

python -m venv .venv
.venvScriptsactivate

仓库原文列出的依赖是 fastapi、openai、uvicorn、dotenv。我实操更建议把 dotenv 写成 python-dotenv，因为代码里用的是 from dotenv import load_dotenv，常规安装包就是它。

如果你想直接使用下面的新 SDK 写法，requirements.txt 可以写成：

fastapi
uvicorn[standard]
python-dotenv
openai>=1.0.0

然后安装：

pip install -r requirements.txt

如果你坚持完全照仓库文本里的旧代码跑，那就把 OpenAI SDK 固定到旧版本：

fastapi
uvicorn[standard]
python-dotenv
openai==0.28.1

我更建议用新 SDK 写法。新版环境里直接跑旧的 openai.ChatCompletion.create，很容易遇到接口移除报错。这个坑不提前说，新手会以为是 API Key 填错了。

配置 .env

在 .env 里放 OpenAI Key 和模型名：

OPENAI_API_KEY=sk-your-openai-key
OPENAI_MODEL=gpt-4o-mini

Key 不要写进 Git，也不要发到公开截图里。调试时如果怀疑环境变量没读到，可以先跑：

python -c "import os; from dotenv import load_dotenv; load_dotenv(); print('ok' if os.getenv('OPENAI_API_KEY') else 'missing')"

能输出 ok，说明 .env 至少被 Python 读到了。

写入 server.py

为了兼容当前 OpenAI Python SDK，我建议用下面这版 server.py。功能和仓库原思路一致，仍然是接收主题、受众、页数，然后返回 ppt_markdown。

import os

from dotenv import load_dotenv
from fastapi import FastAPI, HTTPException
from openai import OpenAI
from pydantic import BaseModel, Field

load_dotenv()

api_key = os.getenv("OPENAI_API_KEY")
model = os.getenv("OPENAI_MODEL", "gpt-4o-mini")

if not api_key:
    raise RuntimeError("OPENAI_API_KEY is missing")

client = OpenAI(api_key=api_key)
app = FastAPI(title="PPT MCP Server")


class PPTRequest(BaseModel):
    topic: str = Field(..., min_length=2)
    audience: str = Field(..., min_length=2)
    slides: int = Field(..., ge=1, le=50)


@app.get("/health")
def health():
    return {"status": "ok", "model": model}


@app.post("/generate-ppt")
def generate_ppt(data: PPTRequest):
    prompt = f"""
你是一名 PPT 演讲设计专家。
请为主题「{data.topic}」、目标受众「{data.audience}」设计 {data.slides} 页 PPT。
请输出完整大纲，并扩展每一页的标题、要点和讲解备注。
请使用 Markdown / Marp 格式输出，每页之间用 --- 分隔。
"""
    try:
        response = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
        )
    except Exception as exc:
        raise HTTPException(status_code=500, detail=str(exc))

    return {"ppt_markdown": response.choices[0].message.content}

我额外加了 /health 和页数限制。前者方便检查服务是否活着，后者避免一次传几百页把请求拖死。简单，但很有用。

启动本地服务

在 ppt_mcp_server 目录里启动：

uvicorn server:app --reload --host 0.0.0.0 --port 8000

看到 Uvicorn running 之类的提示，就可以先打开健康检查：

http://127.0.0.1:8000/health

如果返回 {"status":"ok"}，说明服务本身已经起来。接着测试生成接口：

curl -X POST "http://127.0.0.1:8000/generate-ppt" 
  -H "Content-Type: application/json" 
  -d '{
    "topic": "AI赋能办公",
    "audience": "企业中层管理者",
    "slides": 10
  }'

返回里应该能看到 ppt_markdown。如果只看到一大段 Markdown，不要慌，这就是仓库设计的输出结果。它生成的是 PPT 内容稿，不是直接生成 .pptx 文件。

接入 Chatbox 的调用方式

仓库说明里提到的 Chatbox 调用逻辑很直接：在流程里加一个 HTTP 请求步骤。

配置项	填写内容
请求方法	POST
本地地址	http://127.0.0.1:8000/generate-ppt
线上地址	http://your-server.com/generate-ppt
请求头	Content-Type: application/json
提取字段	ppt_markdown

请求体模板可以这样写：

{
  "topic": "{{topic}}",
  "audience": "{{audience}}",
  "slides": 10
}

如果 Chatbox 和服务在同一台电脑上，本地地址一般能跑。如果 Chatbox 在远程环境里执行，127.0.0.1 就会指向远程机器自己，不会访问你的电脑。这个点很容易误判，我当时也下意识用了 localhost，结果请求根本没打到本机服务。

把 Markdown 变成真正 PPTX

这个服务返回的是 Marp 风格 Markdown。要拿到真正的幻灯片文件，还需要多走一步转换。

如果你使用 Marp CLI，可以先把返回内容保存为 slides.md，再执行：

marp slides.md --pptx

如果只是想在网页里预览，也可以输出 HTML：

marp slides.md --html

这里要分清“生成 PPT 内容”和“生成 PPT 文件”。这个仓库解决的是前半段，后半段需要接 Marp、PPTXGenJS 或其他导出链路。

常见故障排查

现象	常见原因	处理办法
clone 后找不到 server.py	仓库当前只有 PPTMCP.txt，代码没有拆成文件。	手动创建 ppt_mcp_server/server.py、requirements.txt、.env。
ModuleNotFoundError: No module named dotenv	依赖没装好，或 requirements 里写了不稳定的 dotenv。	改用 python-dotenv，再执行 pip install -r requirements.txt。
openai.ChatCompletion.create 报错	旧版 SDK 写法遇到新版 openai 包。	改成 OpenAI() 客户端写法，或把依赖固定为 openai==0.28.1。
接口返回 500	API Key 没读到、模型名不可用，或 OpenAI 请求失败。	先访问 /health，再检查 .env、模型名和服务重启状态。
端口 8000 被占用	本机已有别的服务在用同一端口。	换成 --port 8001，Chatbox 里的 URL 也同步改掉。
Chatbox 调不通本地地址	执行环境不在本机，或防火墙没有放行端口。	本地调试用 127.0.0.1；远程调用建议部署到 Render、Railway 或自有服务器。
返回了 Markdown，但没有 PPTX	服务只生成 Marp 风格内容，不负责文件导出。	把 ppt_markdown 保存成 slides.md，再用 Marp CLI 转 PPTX。

多服务共存时注意端口和命名

如果你本机已经跑了别的 MCP、FastAPI、文档解析或 PPT 生成服务，建议给这个服务单独固定端口，比如 8003，同时在 Chatbox 里把流程节点命名成 ppt-mcp-server-generate。

uvicorn server:app --reload --host 0.0.0.0 --port 8003

对应的 Chatbox URL 改成：

http://127.0.0.1:8003/generate-ppt

端口和节点名都清楚，后面排查会轻松很多。别把几个服务都叫“PPT 生成”，到时候日志一开，自己都分不清是哪一个在报错。

批量生成 PPT 内容的指令模板

如果你要一次生成多份 PPT 内容，可以先让 Agent 或 Chatbox 按主题清单循环请求接口。请求模板可以固定为：

{
  "topic": "{{item.topic}}",
  "audience": "{{item.audience}}",
  "slides": "{{item.slides}}"
}

批量任务可以这样组织：

请调用 ppt-mcp-server 的 /generate-ppt 接口，按下面清单逐个生成 Marp Markdown。

统一要求：
- 每个主题单独保存一份 slides.md
- 每份生成失败时记录错误，不要中断后续任务
- 每份内容都要包含标题、每页要点和讲解备注
- 生成后汇总每份文件路径

任务清单：
1. 主题：AI赋能办公；受众：企业中层管理者；页数：10
2. 主题：新能源行业周报；受众：投研团队；页数：8
3. 主题：Python自动化入门；受众：零基础运营；页数：6

批量跑的时候，页数别一下子拉太大。模型输出太长时，HTTP 请求会变慢，Chatbox 端也更容易超时。

部署到线上时怎么选

仓库文本里提到 Railway、Render、Hugging Face Spaces 都可以作为远程部署平台。实际选择时，我会按调用场景判断。

自己本机用，直接本地跑就行；团队成员都要调用，Render 或 Railway 更省事；如果要做演示页面或公开 demo，再考虑 Hugging Face Spaces。部署后记得把 OPENAI_API_KEY 放到平台的环境变量里，不要写进代码仓库。

线上服务还建议加一个简单访问保护，比如 API Key 请求头、内网限制或网关鉴权。这个仓库原始示例没有鉴权，公网裸露接口会让别人消耗你的模型额度。这个坑成本不小，别省。

安装完成后的收尾确认

到这里，整套流程基本就能跑起来了。我平时会快速核对几个点：PPTMCP.txt 已经拆成真正的 server.py 和 requirements.txt，.env 能读取到 OpenAI Key，/health 正常返回，/generate-ppt 能通过 curl 拿到 ppt_markdown，Chatbox 里能提取这个字段，Marp 转换链路也能把 Markdown 变成 PPTX。

这些都跑通，就说明 duanqiaocxu/ppt-mcp-server 已经可以投入使用。真正用它做 PPT 时，记得把主题、受众、页数写具体一点，输出质量会比一句“帮我做个 PPT”稳定得多。