# What Is PPTX MCP?

## The One-Liner

PPTX MCP is a server that lets any AI assistant create, edit, review, and restyle professional PowerPoint presentations — without templates, without human layout work, and without leaving the conversation.

---

## The Problem It Solves

Creating good slide decks is slow. Even with a clear outline, the actual work — picking layouts, placing elements, matching brand colors, checking alignment, formatting tables, building charts — takes hours. AI assistants can write the *content* for a deck, but they can't produce the actual `.pptx` file. You still have to copy-paste into PowerPoint and manually format everything.

PPTX MCP eliminates that gap entirely. You describe what you want in plain language, and the AI produces a finished, downloadable `.pptx` file. Not a draft. Not a wireframe. A real presentation with proper typography, brand colors, data visualizations, and spatial layout.

---

## How It Works

### The Architecture

PPTX MCP is a **Model Context Protocol (MCP) server**. MCP is an open standard that lets AI assistants (Claude, GPT, etc.) use external tools during a conversation. When you install PPTX MCP, your AI assistant gains 41 specialized tools for working with PowerPoint files.

```
You (natural language)
  → AI Assistant (understands intent, calls tools)
    → PPTX MCP Server (41 tools, runs locally)
      → python-pptx (renders actual .pptx XML)
        → PowerPoint file on your disk
```

Everything runs locally. No cloud API calls. No data leaves your machine. The server processes requests, generates or modifies `.pptx` files, and returns results to the AI assistant, which then responds to you in conversation.

### What Happens When You Say "Build Me a Deck"

1. **Planning** — The AI calls `plan_presentation` with your topic, audience, and key points. The server's planner agent selects from 32 slide types and 27 deck archetypes to build a slide-by-slide definition. No bracket placeholders — every slide gets real content derived from your input.

2. **Rendering** — The AI calls `create_from_plan`. The generator walks each slide definition and renders it: positions text boxes, builds charts from data, lays out card grids, applies brand colors and fonts, adds shadows and accent bars, handles connectors between shapes. Each slide type has its own rendering engine.

3. **Review** — The AI can call `review_presentation` to run 26 design rules against the output. The review engine checks layout density, text overflow, element overlap, font compliance, color consistency, accessibility contrast ratios, and narrative flow. It returns a score and specific issues.

4. **Iteration** — If issues are found, `improve_presentation` applies auto-fixes (title casing, font size floors, off-brand color correction) and re-renders. The AI can also make targeted edits with element-level tools.

This entire cycle — plan, render, review, fix — can happen in a single conversation without you touching PowerPoint.

---

## What's In the Box

### 40 MCP Tools

**Create & Structure**
| Tool | What It Does |
|------|-------------|
| `generate_presentation` | One-shot: plan + render in a single call (best for 3-6 slides) |
| `plan_presentation` | Build a slide plan with server-side caching (best for 7+ slides) |
| `create_from_plan` | Render a cached plan to `.pptx` |
| `create_presentation` | Render a raw `PresentationDefinition` JSON to `.pptx` |
| `add_slide` | Insert a new slide at any position |
| `update_slide` | Replace a slide's definition |
| `delete_slide` / `move_slide` / `duplicate_slide` | Structural operations |
| `reorder_slides` | Rearrange slide order in one call |
| `add_speaker_notes` | Add presenter notes to any slide |

**Read & Analyze**
| Tool | What It Does |
|------|-------------|
| `read_presentation` | Parse a `.pptx` into structured JSON (round-trip capable) |
| `analyze_presentation` | Deep analysis: parse + describe + review in one call |
| `review_presentation` | Run 26 design rules, get score + specific issues |
| `validate_slide_layout` | Per-slide spatial check (overlaps, bounds, spacing) |

**Edit Elements**
| Tool | What It Does |
|------|-------------|
| `list_slide_elements` | See every shape with position, size, text, font |
| `modify_element` | Change any property of a single shape |
| `add_element` | Add a textbox, shape, or image to an existing slide |
| `delete_element` / `copy_element` | Remove or duplicate shapes |
| `align_elements` | Align or distribute elements (left, center, top, etc.) |
| `group_elements` / `ungroup_elements` | Group or dissolve shape groups |
| `find_and_replace` | Search/replace text across all or specific slides |
| `batch_modify_elements` | Apply multiple modifications in one call |

**Brand & Style**
| Tool | What It Does |
|------|-------------|
| `apply_brand_guidelines` | Apply a brand config to an existing presentation |
| `restyle_presentation` | Ingest a deck, re-generate with a new brand |
| `generate_brand_guide` | Create a visual brand guide `.pptx` |
| `parse_brand_guide` | Convert markdown/YAML brand spec to config |
| `extract_brand` | Analyze an existing `.pptx` and infer its brand config |
| `get_brand_presets` | List the 12 built-in brand presets |

**AI Agents**
| Tool | What It Does |
|------|-------------|
| `optimize_design` | Designer agent refines layout and visual hierarchy |
| `improve_presentation` | Iterator agent auto-fixes review issues |
| `parse_spec` | Convert a markdown specification into a full presentation |

**Discovery & Safety**
| Tool | What It Does |
|------|-------------|
| `get_slide_templates` | Browse all 32 slide types with field examples |
| `get_deck_types` | Browse all 27 deck archetypes |
| `get_plan_slide` / `update_plan_slide` | Inspect or modify individual slides in a cached plan |
| `optimize_plan` | Run design optimization on a cached plan (server-side, token-efficient) |
| `create_checkpoint` / `restore_checkpoint` | Undo via file backup |

### 9 Guided Prompts

Prompts are pre-built conversation starters that walk the AI through a specific workflow:

- `choose_workflow` — Recommends the right approach based on deck size
- `create_pitch_deck` — Startup pitch with investor framing
- `create_board_update` — Board-level executive summary
- `create_sales_deck` — Customer-facing sales narrative
- `create_all_hands` — Company-wide update
- `create_consulting_deck` — Strategy deck with consulting archetypes
- `review_and_improve` — Review → auto-fix → re-review loop
- `add_process_flow` — Add a process/workflow visualization
- `design_guidance` — Professional design principles reference

### 32 Slide Types

Every slide type has its own rendering engine with purpose-built layout logic:

**Narrative**: title, section, content, two_column, quote, big_number, closing
**Data**: chart (12 chart types), table, dashboard, comparison, pros_cons
**Visual**: image_text, icon_grid, card_grid, team, process, timeline, step_cards, funnel, agenda, swot
**Diagrams**: org_chart, matrix, pyramid, venn, waterfall, hub_spoke, cycle, gantt
**Utility**: blank, diagram (generic)

### 12 Chart Types

bar, line, pie, column, area, scatter, bubble, radar, doughnut, stacked_bar, stacked_column, combo

Charts are rendered using python-pptx's native chart engine — they're real, editable PowerPoint charts with data tables, not images.

### 27 Deck Archetypes

Pre-built deck structures with appropriate slide sequences for common use cases:

**General**: pitch_deck, board_deck, sales_deck, all_hands, project_update, training, product_launch, case_study, quarterly_earnings, onboarding, annual_report, conference_talk

**Consulting**: strategy_deck, due_diligence, market_analysis, org_design, competitive_assessment, transformation_roadmap, assessment, opportunity_assessment, strategy_training, template_guide, executive_overview, analysis_deck, cost_breakdown, architecture_review, analytics_dashboard

### 12 Brand Presets

Each preset defines colors, fonts, spacing, shape styles, and tone:

| Preset | Primary Color | Fonts | Character |
|--------|--------------|-------|-----------|
| executive | Navy #1B2A4A | Aptos/Aptos | Boardroom-serious |
| technical | Dark gray #263238 | Segoe UI | Engineering-precise |
| minimal | Black #111111 | Arial | Clean, no decoration |
| creative | Purple #6B21A8 | Georgia/Aptos | Bold, expressive |
| corporate | Steel blue #1E3A5F | Garamond/Aptos | Traditional authority |
| consulting | Deep blue #1A3C6E | Aptos/Aptos | Strategy-firm polish |
| healthcare | Blue #0D6EAE | Aptos | Clinical trust |
| startup | Violet #6C5CE7 | Aptos Display | Modern energy |
| academic | Burgundy #800020 | Garamond/Aptos | Scholarly weight |
| government | Navy #003366 | Aptos | Institutional calm |
| finance | Forest #1A3C34 | Aptos Display | Money-serious |
| nonprofit | Warm orange #E07C3E | Aptos Display | Approachable warmth |

You can also define fully custom brands with 60+ configurable properties (colors, fonts, spacing, shadows, edge bars, dividers, logo placement, header/footer).

### 25 Shape Types

rectangle, rounded_rectangle, circle, oval, arrows (4 directions), chevron, diamond, triangle, pentagon, hexagon, callout, octagon, stars, heart, lightning, cloud, block_arc, cross, donut, no_symbol

---

## What Makes It Different

### 1. It Generates Real PowerPoint Files

Not images. Not PDFs. Not HTML mockups. Actual `.pptx` files that open in PowerPoint, Keynote, and Google Slides. Every element is editable — you can move shapes, change text, modify chart data, recolor fills. The output is a starting point you own, not a locked artifact.

### 2. It Understands Layout, Not Just Content

Most AI-to-slides tools dump text onto slides and call it done. PPTX MCP has a spatial layout engine that:

- Calculates grid positions based on element count and content area
- Applies brand-appropriate margins, spacing, and padding
- Caps card heights to prevent footer overflow
- Adjusts column ratios for balanced visual weight
- Runs 26 post-generation design rules to catch layout problems

It's not pixel-perfect — this is programmatic layout, not a design tool. But it produces results that are structurally sound and visually consistent.

### 3. It's a Tool, Not a Template

Template-based systems give you 10-20 fixed layouts and you pour content into them. PPTX MCP generates layouts dynamically from 32 slide types, each with configurable elements. A DASHBOARD with 3 KPIs looks different from one with 6. A CARD_GRID with a callout reserves space for it. A TABLE with 4 columns gets different proportions than one with 8.

### 4. Brand Is a First-Class Concept

Every visual decision — colors, fonts, spacing, shadows, corner radii, accent bars, divider styles — flows from a brand configuration. Change the brand, and the entire deck re-renders consistently. You can:

- Use one of 12 built-in presets
- Define a custom brand in YAML/markdown
- Extract a brand from an existing `.pptx` file
- Restyle any deck with a different brand in one call

### 5. It Works With Any MCP-Compatible AI

Claude Desktop, Claude Code, Cursor, Windsurf, VS Code with Copilot — any AI client that supports MCP can use PPTX MCP. The server is AI-agnostic. The tools are the same regardless of which assistant calls them.

### 6. Everything Runs Locally

No API keys for the PPTX engine. No cloud rendering. No data transmission. The server runs as a local process, reads and writes files on your disk, and communicates with the AI client over stdio. Your presentation content never leaves your machine (beyond whatever you share with the AI assistant itself).

### 7. Round-Trip Editing

You can read an existing `.pptx`, parse it into a structured definition, modify it, and write it back. The parser extracts slide types, text content, shapes, colors, fonts, table data, and chart configurations. This enables:

- **Restyling**: Take a deck built in one brand and re-render it in another
- **Review**: Run design rules against any `.pptx`, not just ones this tool created
- **Incremental editing**: Modify individual elements without regenerating the whole deck

---

## How It's Built

### Tech Stack

- **Python 3.11+** with full type hints
- **python-pptx** for PowerPoint XML generation
- **FastMCP** for Model Context Protocol server implementation
- **Pydantic** for all data models (strict validation, serialization)
- **No LLM dependency** — the server itself doesn't call any AI APIs. All intelligence comes from the AI assistant that calls the tools.

### Code Structure

```
pptx_mcp/           ~19,400 lines of Python
  server.py          41 tools, 9 prompts, 2 resources
  models/            Pydantic models (slides, brand, review, editor, diagrams)
  engine/            Generator, parser, layouts, charts, shapes, composition
    diagrams/        8 diagram renderers (org chart, Venn, waterfall, etc.)
  brand/             Brand config resolution + 12 preset definitions
  agents/            Planner, designer, reviewer, iterator, archetypes
  review/            Review engine + 26 design rules + spatial validation
  utils/             Error types, logging, path validation
tests/               ~11,100 lines, 1,199 tests
scripts/             Test deck generator (12 visual QA decks)
```

### Key Design Decisions

**No LLM in the loop.** The server is deterministic. Given the same input definition and brand config, it produces the same output every time. The AI assistant provides the intelligence (topic interpretation, content generation, tool selection); the server provides the rendering capability. This means the tool works with any AI, and the rendering quality is independent of model quality.

**Pydantic all the way down.** Every data structure — slide definitions, brand configs, review results, element modifications — is a Pydantic model with validation. The AI sends JSON, FastMCP deserializes it into typed models, and invalid input is caught before rendering. This prevents a huge class of "garbage in, garbage out" failures.

**Layout is math, not heuristics.** The composition engine uses a `LayoutGrid` with explicit margins, column/row calculations, and cell placement. Cards go into grid cells. KPIs get distributed across rows. The grid adapts to element count, available space, and callout presence. It's not magic — it's arithmetic with sensible defaults.

**Brand propagates everywhere.** Colors, fonts, spacing, shape styles — every renderer reads from the brand config. There's no hardcoded blue or hardcoded Arial anywhere in the rendering pipeline. If you change the brand, everything changes.

---

## Numbers at a Glance

| Metric | Value |
|--------|-------|
| MCP Tools | 41 |
| Guided Prompts | 9 |
| Slide Types | 32 |
| Chart Types | 12 |
| Diagram Types | 8 |
| Shape Types | 25 |
| Deck Archetypes | 27 |
| Brand Presets | 12 |
| Design Review Rules | 26 |
| Auto-Fix Patterns | 7 |
| Test Count | 1,199 |
| Source Lines | ~19,400 |
| Test Lines | ~11,100 |
| External Dependencies | python-pptx, Pydantic, FastMCP |
| Cloud Dependencies | None |
| Version | 0.8.7 |

---

## What It's Good At Today

- **Simple to mid-complexity decks** (content, tables, charts, dashboards, card grids) — B+ quality
- **Brand consistency** across any number of slides — every element matches the config
- **Executive/board decks** — the board_deck archetype scores 7.6/10 on its own review engine
- **Restyling existing decks** — ingest → re-render with different brand works reliably
- **Markdown-to-PPTX** — write a spec in markdown, get a formatted deck (8.3/10 review score)
- **Iterative refinement** — review → fix → re-review loop catches and resolves layout issues

## Where It's Still Maturing

- **Complex diagrams** (Venn, hub-spoke, cycle) — elements are undersized, need density tuning
- **Chart overflow** — native charts can extend past the content zone in some configurations
- **Image slides** — currently underutilized (10% coverage), needs full-bleed hero layout
- **Review engine scoring** — some false positives on diagram slides inflate issue counts

---

## How to Install

```bash
pip install pptx-mcp
```

Add to your AI client's MCP configuration:

```json
{
  "mcpServers": {
    "pptx": {
      "command": "python",
      "args": ["-m", "pptx_mcp.server"]
    }
  }
}
```

That's it. The next time you open your AI assistant, it has 41 new tools for building presentations.

---

## License

MIT. Open source. Use it however you want.
