Gerador de Apresentações MCP
haandol/ppt-generator
Gera apresentações PowerPoint automaticamente via MCP sem API keys
Ver no GitHubServidor MCP que gera apresentações automaticamente a partir de um tema, delegando a geração de conteúdo para o cliente LLM. Valida e pós-processa JSON determinístico em etapas prepare/ingest, sem custo por chamada no servidor. Funciona nativamente como plugin Claude Code e com qualquer cliente MCP compatível.
Instalação
npx convez-ai haandol/ppt-generator1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Criar apresentações executivas rapidamente a partir de tópicos
- Gerar múltiplas variações de deck com estilos diferentes
- Integrar geração de slides em workflows automáticos e agentes
Veredito

Solução bem arquitetada que délega inteligentemente a geração LLM para o cliente, evitando custo de modelo no servidor. Implementação clara com suporte a múltiplas plataformas (Claude Code, Kiro, clientes MCP genéricos) — recomendado para quem precisa automatizar criação de apresentações em pipelines maiores.
README
A tradução para o português deste README ainda está na fila.
PPT Generator
An MCP (Model Context Protocol) server that automatically generates presentations from a given topic.
LLM generation is offloaded to the client. The server owns the prompts, the output
JSON schemas, and all deterministic post-processing (validation, layout, lint, HTML/PPTX
render); it never calls a model itself. Each generation step is a prepare_* /
ingest_* pair — prepare_* hands the client the prompt + schema, the client generates
the JSON, and ingest_* validates and post-processes it. This means no AWS/Anthropic
credentials and no per-call model cost on the server side — the client's own model does
the generating. See the ADR index under docs/adr/ for the design rationale.
Prerequisites
- Python 3.13+
- uv package manager
- Claude Code (recommended — the plugin bundles the MCP server + workflow skills). Any MCP client that can generate JSON also works — no model API keys needed on the server.
1. Install as a Claude Code plugin (recommended)
The repo ships as a Claude Code plugin (manifest at .claude-plugin/plugin.json) that
registers the MCP server and the ppt-outline / ppt-design / ppt-speaker-script / ppt-modify /
ppt-visual-qa skills which drive the prepare→generate→ingest workflow.
Add the marketplace and install the plugin from within Claude Code:
/plugin marketplace add haandol/ppt-generator
/plugin install ppt-generator@ppt-generator
The plugin runs the MCP server via uv run against the plugin's own checkout
(${CLAUDE_PLUGIN_ROOT}), so uv must be on your PATH and the plugin's dependencies
must be synced. If the server fails to start, sync deps once from the plugin directory:
uv sync # run inside the installed plugin's directory
No model API keys are required — the client supplies the generation.
Alternative — clone and register the MCP server directly
If you are not using the Claude Code plugin system (e.g. Kiro / Claude Desktop, or you prefer a local clone), clone the repo and register just the MCP server:
git clone https://github.com/haandol/ppt-generator.git
cd ppt-generator
uv sync
{
"mcpServers": {
"ppt-generator": {
"command": "uv",
"args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"]
}
}
}
Replace
/path/to/ppt-generatorwith the actual project path. This registers the MCP server only; the workflow skills are Claude Code plugin skills.
Use it as a skill in Kiro / Codex
The workflow is just the MCP server plus the prepare_*/ingest_* handshake, so any
MCP client that can generate JSON can drive it — including Kiro and Codex. The
repo ships the entry points each harness loads automatically (Kiro steering at
.kiro/steering/ppt-generator.md, Codex guidance in AGENTS.md), so you get the same
skill-level guidance without duplicating the prompts.
First clone and sync once (no model API keys needed):
git clone https://github.com/haandol/ppt-generator.git
cd ppt-generator
uv sync
Kiro — copy the bundled example and fix the path, then Kiro auto-loads the steering:
cp .kiro/settings/mcp.json.example .kiro/settings/mcp.json
# edit .kiro/settings/mcp.json → replace /path/to/ppt-generator with your clone path
{
"mcpServers": {
"ppt-generator": {
"command": "uv",
"args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"],
"disabled": false,
"autoApprove": ["export_html", "load_project_status", "list_projects"]
}
}
}
Use ~/.kiro/settings/mcp.json instead for a global (all-workspace) registration.
Codex — register the MCP server via CLI or ~/.codex/config.toml:
codex mcp add ppt-generator -- uv --directory /path/to/ppt-generator run ppt-generator
# ~/.codex/config.toml
[mcp_servers.ppt-generator]
command = "uv"
args = ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"]
Codex reads the repo's AGENTS.md for the prepare/ingest workflow guidance. See
docs/harness/kiro-codex.md for the full walkthrough
(Visual QA setup, custom Codex prompt, per-harness entry-point table).
For the full list of environment variables and detailed client / plugin configurations, see docs/harness/environment.md.
2. Usage
You interact in natural language; the client drives the prepare→generate→ingest handshake
behind the scenes (guided by the bundled skills). You don't call the prepare_*/ingest_*
tools by hand — just describe what you want.
Tool-client update for 0.8.1
Visual QA clients must pass the prepared_context returned by
prepare_visual_qa_analysis to ingest_visual_qa_analysis. The bundled skill
does this automatically. Restart in-flight analysis from prepare after upgrading;
results without that context, or with changed slide/intent/screenshot inputs, are
rejected before they can authorize a visual fix.
Step 1 — Generate or Import PPT
Create new — Prepare your content in a file like context.md, then request via your MCP client:
Read @context.md and generate a PPT using ppt-generator.
The client generates the outline JSON, then the per-slide design specs, following the
prompts and schemas the server hands back — no model credentials on the server side.
The ppt-speaker-script skill then writes the spoken script from the actual deck.
Its writing guide covers read-aloud wording, grounded claims, slide transitions,
and timing without tying the workflow to a particular customer or language.
Import existing PPTX — You can also import an existing PPTX file for editing:
Import @presentation.pptx using import_pptx.
Importing automatically generates an HTML preview. You can skip Step 2 and directly use per-slide editing, Visual QA, and export features. Parsing is deterministic with no LLM calls.
Step 2 — Provide Project Information
Before outline generation, you will be asked for the following:
- Presentation purpose — e.g., "internal tech sharing", "client proposal", "conference talk"
- Presentation duration — 3–60 minutes (default: 15 minutes)
- Audience type —
general/technical/executive - Presenter info — name / title / organization
The flow proceeds Outline → DESIGN.md (design intent) → per-slide Design Spec → Speaker Script → deck review → Visual QA → final export. A complete-deck request can proceed through these stages without a separate outline approval. You can request an outline-only result, omit script generation, or edit at each stage.
Speaker scripts and notes
Ask for a script or revise notes without regenerating the visual slides:
Write an English speaker script for this deck for a 15-minute online introduction.
Revise only slide 3's notes and keep the rest of the script unchanged.
The skill uses prepare_speaker_script / ingest_speaker_script to validate and
save only the notes. Generated and imported decks both work. Preparation includes
the actual slides and existing notes; stale submissions are rejected if the deck
changes. The completion checkpoint exports speaker-script.md, HTML, and PPTX
from the same saved notes. Re-export the script with export_speaker_script after
slide moves or edits so its order and headings match the current deck. Calculated
timing is an estimate; a read-through still verifies the presenter's actual pace.
Step 3 — Edit Individual Slides (Optional)
After design spec generation (or PPTX import), you can modify individual slides. Instead of regenerating everything, you can add, update, delete, move, or make narrow single-component edits:
Add a bar chart comparing performance data below the diagram on slide 3.
Slide 5 has too much text — reduce it to key bullet points with icon layout.
Add a Q&A slide after slide 7.
Make the "LLM" box on slide 4 red.
Move slide 6 to position 2.
Add/update/component edits use the prepare/ingest handshake; move and delete are pure file operations with no generation.
Step 4 — Visual QA
Detects and fixes visual defects (line breaks, overlaps, margin misalignment, etc.). The server captures screenshots (Playwright); the client analyzes them and generates fixes via the prepare/ingest handshake. Does not run automatically — must be explicitly requested.
Prerequisites:
uv sync --group visual-qa
uv run --group visual-qa playwright install chromium
Run visual QA.
End-to-end deck requests include read-only Visual QA and issue-scoped low-risk patches. If Playwright is unavailable, provide a client-captured PNG through
screenshot_path. Content, data, element-count, and slide-count changes still require user confirmation.
Step 5 — Export Files
After the design spec is finalized, request an HTML preview:
Export as HTML and open it.
To export in PPTX format:
Export as PPT and open it.
Debug Logging
The MCP server uses stdio communication, so stdout logs cannot be viewed directly. Enable file logging to write debug-level logs to a file.
Configuration
When registering the MCP server directly, add PPT_LOG_DIR to the env section:
{
"mcpServers": {
"ppt-generator": {
"command": "uv",
"args": ["--directory", "/path/to/ppt-generator", "run", "ppt-generator"],
"env": {
"PPT_LOG_DIR": "/tmp/ppt-generator"
}
}
}
}
When installed as a Claude Code plugin, set
PPT_LOG_DIRin your Claude Code MCP environment for theppt-generatorserver. See docs/harness/environment.md.
Environment Variables
| Variable | Description |
|---|---|
VISUAL_QA_PARALLEL | Number of parallel screenshot-capture workers for Visual QA (Playwright, server-side; default: 8). Analysis/fix generation runs on the client |
VISUAL_QA_MAX_ITERATIONS | Maximum fix iterations for Visual QA (default: 2) |
SCREENSHOT_TIMEOUT | Per-slide screenshot capture timeout in seconds (default: 60) |
PPT_LOG_DIR | Directory for per-project log files (recommended). e.g., /tmp/ppt-generator |
PPT_LOG_FILE | Single log file path (legacy). Ignored when PPT_LOG_DIR is set |
- Log files rotate at 10MB with 2 backups retained.
- When
PPT_LOG_DIRis set, a<project_id>.logfile is created for each project.
Viewing Logs
# View logs for a specific project
tail -f /tmp/ppt-generator/<project_id>.log
# View all logs
tail -f /tmp/ppt-generator/*.log
Development
uv run ppt-generator # Run MCP server (stdio mode)
python3 scripts/verify.py # Locked checks, tests, build, and wheel smoke
uv run --locked pytest # Run tests directly while debugging
Documentation
- Design and contracts: Architecture, Schemas
- Setup: Environment & Config, Kiro / Codex
- Verification and delivery: Testing, Release
- Development decisions: ADR, Contributing Guide