Metadata-Version: 2.4
Name: pptx-mcp
Version: 0.1.0
Summary: Model Context Protocol server for programmatic PowerPoint generation
Author: swak
License-Expression: MIT
License-File: LICENSE
Keywords: ai,mcp,powerpoint,pptx,presentation
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: mcp>=1.20.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-pptx>=1.0.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# PPTX MCP

**AI-Powered PowerPoint Generation**

[![PyPI version](https://img.shields.io/pypi/v/pptx-mcp)](https://pypi.org/project/pptx-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP Compatible](https://img.shields.io/badge/MCP-compatible-purple)](https://modelcontextprotocol.io)

Made by [swak](https://github.com/swak)

---

## What This Does

PPTX MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants create, edit, and review real PowerPoint files. It produces native `.pptx` files with 23 slide types, 5 brand presets, and a built-in review engine that scores your decks and auto-fixes design issues. The output opens in PowerPoint, Keynote, or Google Slides -- fully editable, no lock-in.

## Why Use This

- **Real editable files** -- not images, not PDFs. Native `.pptx` you can open, edit, and present.
- **23 slide types** -- title, content, charts, tables, timelines, dashboards, SWOT, funnels, team bios, and more.
- **Review engine** -- scores decks 0-10, catches design issues, and auto-improves them.
- **Brand consistency** -- 5 built-in presets or bring your own brand config (colors, fonts, spacing, rules).
- **Round-trip editing** -- read existing decks, modify individual slides, re-render with new branding.
- **Deck archetypes** -- 6 templates (pitch deck, board update, sales deck, etc.) for intelligent slide selection.

<!-- TODO: Add 3-5 example slide screenshots -->

---

## Quick Start

### Option 1: uvx (recommended)

Zero-install for any MCP client. Requires [uv](https://docs.astral.sh/uv/).

```bash
uvx pptx-mcp serve
```

### Option 2: pip install

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

### Option 3: From source

```bash
git clone https://github.com/swak/pptx-mcp.git
cd pptx-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
pptx-mcp serve
```

---

## Connecting to AI Tools

### Claude Code

```bash
claude mcp add pptx-mcp -- uvx pptx-mcp serve
```

Or add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

<details>
<summary>Using a local install instead of uvx?</summary>

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "/absolute/path/to/pptx-mcp/.venv/bin/python",
      "args": ["-m", "pptx_mcp.server"]
    }
  }
}
```
</details>

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

<details>
<summary>Using a local install instead of uvx?</summary>

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "/absolute/path/to/pptx-mcp/.venv/bin/python",
      "args": ["-m", "pptx_mcp.server"]
    }
  }
}
```
</details>

### Cursor

Add to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

### Windsurf

Add to your Windsurf MCP config:

```json
{
  "mcpServers": {
    "pptx-mcp": {
      "command": "uvx",
      "args": ["pptx-mcp", "serve"]
    }
  }
}
```

---

## What You Can Do

Once connected, your AI assistant has access to 16 tools:

| Tool | What to ask |
|------|-------------|
| `generate_presentation` | "Create a 10-slide deck on cloud migration" |
| `plan_presentation` | "Plan a 12-slide deck on AI adoption for the board" |
| `create_presentation` | "Render this slide plan as a PowerPoint file" |
| `add_slide` | "Add a pros/cons slide after slide 3" |
| `update_slide` | "Replace slide 5 with a chart showing Q1-Q4 revenue" |
| `delete_slide` | "Remove slide 8" |
| `move_slide` | "Move slide 2 to the end" |
| `duplicate_slide` | "Duplicate slide 4" |
| `read_presentation` | "Read my existing deck at ~/deck.pptx" |
| `review_presentation` | "Review my deck and tell me what to fix" |
| `improve_presentation` | "Auto-improve my deck and save a new version" |
| `apply_brand_guidelines` | "Re-style my deck using the minimal preset" |
| `optimize_design` | "Optimize the layout of this slide plan" |
| `get_slide_templates` | "Show me what slide types are available" |
| `get_brand_presets` | "What brand styles can I use?" |
| `get_deck_types` | "What deck archetypes are available?" |

**Workflows:**

- **Single-step**: Use `generate_presentation` to go from topic to `.pptx` in one call.
- **Two-step**: Use `plan_presentation` to get a slide plan, review/edit it, then `create_presentation` to render.
- **Edit existing**: Use `read_presentation` to parse a deck, then `add_slide` / `update_slide` / `delete_slide` to modify it.
- **Review loop**: Use `review_presentation` to score a deck, then `improve_presentation` to auto-fix issues.

---

## Example Conversation

**You:** Create an executive presentation about migrating our payment system to Stripe. 8 slides. Save to ~/Desktop/stripe_migration.pptx

**Claude will:**
1. Call `plan_presentation` to generate a structured slide plan
2. Call `create_presentation` to render the `.pptx` file
3. Summarize what's in each slide

**You:** Read it back and review it

**Claude will:**
1. Call `read_presentation` to parse the file
2. Call `review_presentation` to score it (e.g., 8.5/10) and list issues

**You:** Fix the issues and save as v2

**Claude will:**
1. Call `improve_presentation` to auto-fix issues and re-render
2. Report the before/after scores and changes made

---

## Slide Types

23 slide types are available. Here are the JSON definitions for each.

### Title

```json
{ "slide_type": "title", "title": "Quarterly Review", "subtitle": "Q4 2025" }
```

### Section

```json
{ "slide_type": "section", "title": "Market Analysis", "subtitle": "Deep dive into trends" }
```

### Content

```json
{
  "slide_type": "content",
  "title": "Key Findings",
  "bullets": ["Revenue grew 15%", "Retention at 92%", "NPS improved to 67"]
}
```

Body text variant:

```json
{
  "slide_type": "content",
  "title": "Executive Summary",
  "body": "The migration program is on track to deliver $2.1M in annual savings by Year 3."
}
```

### Two Column

```json
{
  "slide_type": "two_column",
  "title": "Before vs After",
  "columns": [
    { "title": "Before", "bullets": ["Manual process", "5-day turnaround", "Error-prone"] },
    { "title": "After", "bullets": ["Automated", "Same-day", "99.9% accuracy"] }
  ]
}
```

### Pros and Cons

```json
{
  "slide_type": "pros_cons",
  "title": "Build vs Buy",
  "pros": ["Full control", "Custom fit", "No vendor lock-in"],
  "cons": ["Higher cost", "Longer timeline", "Maintenance burden"]
}
```

### Comparison

```json
{
  "slide_type": "comparison",
  "title": "Platform Options",
  "columns": [
    { "title": "AWS", "bullets": ["Broadest services", "Mature ecosystem"] },
    { "title": "Azure", "bullets": ["AD integration", "Enterprise focus"] },
    { "title": "GCP", "bullets": ["ML/AI strength", "Competitive pricing"] }
  ]
}
```

### Chart

```json
{
  "slide_type": "chart",
  "title": "Revenue Trend",
  "elements": [{
    "type": "chart",
    "chart_type": "bar",
    "title": "Revenue by Quarter ($M)",
    "data": {
      "categories": ["Q1", "Q2", "Q3", "Q4"],
      "series": [
        { "name": "2024", "values": [10, 12, 11, 14] },
        { "name": "2025", "values": [13, 15, 16, 18] }
      ]
    }
  }]
}
```

Chart types: `bar`, `line`, `pie`, `column`, `area`

### Table

```json
{
  "slide_type": "table",
  "title": "Team Allocation",
  "elements": [{
    "type": "table",
    "header_row": true,
    "rows": [
      [{ "text": "Team" }, { "text": "Headcount" }, { "text": "Budget" }],
      [{ "text": "Engineering" }, { "text": "24" }, { "text": "$3.2M" }],
      [{ "text": "Product" }, { "text": "8" }, { "text": "$1.1M" }]
    ]
  }]
}
```

### Diagram

```json
{
  "slide_type": "diagram",
  "title": "System Architecture",
  "elements": [
    { "type": "shape", "shape_type": "rounded_rectangle", "text": "API Gateway",
      "position": { "left": 1, "top": 2, "width": 2, "height": 1 } },
    { "type": "shape", "shape_type": "rounded_rectangle", "text": "Service",
      "position": { "left": 5, "top": 2, "width": 2, "height": 1 } }
  ]
}
```

### Blank

```json
{ "slide_type": "blank" }
```

### Quote

```json
{
  "slide_type": "quote",
  "body": "The best way to predict the future is to create it.",
  "quote_attribution": "Peter Drucker",
  "quote_attribution_role": "Management Consultant"
}
```

### Big Number

```json
{
  "slide_type": "big_number",
  "body": "47%",
  "title": "Customer Satisfaction Score",
  "subtitle": "Q4 2025 Results",
  "bullets": ["Up from 32% last quarter"]
}
```

### Process

```json
{
  "slide_type": "process",
  "title": "Implementation Plan",
  "active_step": 1,
  "steps": [
    { "title": "Discovery", "description": "Gather requirements", "status": "completed" },
    { "title": "Design", "description": "Create architecture", "status": "active" },
    { "title": "Build", "description": "Implement solution", "status": "future" }
  ]
}
```

### Timeline

```json
{
  "slide_type": "timeline",
  "title": "Project Milestones",
  "steps": [
    { "title": "Kickoff", "date": "Jan 2025", "status": "completed" },
    { "title": "Beta", "date": "Mar 2025", "status": "active" },
    { "title": "GA Release", "date": "Jun 2025", "status": "future" }
  ]
}
```

### Step Cards

```json
{
  "slide_type": "step_cards",
  "title": "How It Works",
  "steps": [
    { "title": "Sign Up", "description": "Create your account in minutes" },
    { "title": "Configure", "description": "Set your preferences" },
    { "title": "Launch", "description": "Go live with one click" }
  ]
}
```

### Dashboard

```json
{
  "slide_type": "dashboard",
  "title": "Key Metrics",
  "kpis": [
    { "value": "$1.2M", "label": "Revenue", "change": "+15%", "trend": "up" },
    { "value": "92%", "label": "Retention", "change": "+3%", "trend": "up" },
    { "value": "67", "label": "NPS Score", "change": "-2", "trend": "down" },
    { "value": "4.2s", "label": "Avg Response", "trend": "neutral" }
  ]
}
```

### Image + Text

```json
{
  "slide_type": "image_text",
  "title": "Our Product",
  "image_path": "/path/to/product.png",
  "image_position": "left",
  "body": "Next-generation platform for enterprise teams.",
  "bullets": ["Fast deployment", "Built-in analytics", "24/7 support"]
}
```

### Icon Grid

```json
{
  "slide_type": "icon_grid",
  "title": "Our Values",
  "icons": [
    { "icon": "star", "title": "Speed", "description": "Ship fast, iterate often" },
    { "icon": "shield", "title": "Trust", "description": "Transparent by default" },
    { "icon": "bulb", "title": "Innovation", "description": "Question everything" }
  ]
}
```

### Team

```json
{
  "slide_type": "team",
  "title": "Leadership Team",
  "team_members": [
    { "name": "Jane Smith", "role": "CEO", "bio": "20 years in enterprise SaaS" },
    { "name": "John Doe", "role": "CTO", "bio": "Former VP Engineering at Acme" }
  ]
}
```

### Closing

```json
{
  "slide_type": "closing",
  "title": "Thank You",
  "subtitle": "Questions? Let's connect.",
  "cta_text": "Schedule a Demo",
  "contact_info": ["hello@company.com", "+1 (555) 123-4567"]
}
```

### SWOT

```json
{
  "slide_type": "swot",
  "title": "SWOT Analysis",
  "swot": {
    "strengths": ["Strong brand", "Loyal customers"],
    "weaknesses": ["High costs", "Limited reach"],
    "opportunities": ["New markets", "Partnerships"],
    "threats": ["Competition", "Regulation"]
  }
}
```

### Funnel

```json
{
  "slide_type": "funnel",
  "title": "Sales Pipeline",
  "funnel_stages": [
    { "label": "Prospects", "value": "10,000", "description": "Website visitors" },
    { "label": "Leads", "value": "2,500", "description": "Form submissions" },
    { "label": "Qualified", "value": "800", "description": "Sales-qualified leads" },
    { "label": "Closed", "value": "120", "description": "Won deals" }
  ]
}
```

### Agenda

```json
{
  "slide_type": "agenda",
  "title": "Today's Agenda",
  "active_agenda_item": 1,
  "agenda_items": [
    { "title": "Opening Remarks", "status": "completed" },
    { "title": "Q4 Financial Review", "description": "Revenue, margins, forecast", "status": "active" },
    { "title": "2026 Strategic Priorities", "status": "upcoming" },
    { "title": "Q&A", "status": "upcoming" }
  ]
}
```

### Speaker Notes

Any slide type supports speaker notes:

```json
{
  "slide_type": "content",
  "title": "Key Metrics",
  "bullets": ["Revenue: $14M", "Margin: 42%"],
  "speaker_notes": "Emphasize the margin improvement -- strongest signal for the board."
}
```

---

## Brand Configuration

### Built-in Presets

| Preset | Style | Primary | Accent | Font |
|--------|-------|---------|--------|------|
| `executive` | Clean, navy/white | `#1B2A4A` | `#E8913A` | Calibri |
| `technical` | Dark, teal accents | `#263238` | `#00BCD4` | Segoe UI |
| `minimal` | High-contrast B&W | `#111111` | `#FF4444` | Arial |
| `creative` | Bold, colorful | `#6B21A8` | `#F59E0B` | Georgia |
| `corporate` | Conservative, formal | `#1E3A5F` | `#C9A84C` | Times New Roman |

Use presets via CLI (`--preset executive`) or in tool calls (`brand_preset="executive"`).

### Custom Brand Config

Create a YAML file:

```yaml
name: "Your Company"

colors:
  primary: "#002B5C"
  secondary: "#0066CC"
  accent: "#FF6B00"
  background: "#FFFFFF"
  text_primary: "#1A1A1A"
  text_secondary: "#666666"
  chart_colors: ["#002B5C", "#0066CC", "#FF6B00", "#28A745"]

fonts:
  heading_font: "Arial"
  body_font: "Arial"
  title_size: 36
  heading_size: 28
  body_size: 16

spacing:
  margin_left: 0.75
  margin_right: 0.75
  content_top: 1.6
  column_gap: 0.5

layout_rules:
  max_bullets_per_slide: 5
  max_words_per_bullet: 12
  max_words_per_slide: 60

tone: "executive"
footer_text: "Confidential -- Your Company"
```

Use via CLI:

```bash
pptx-mcp generate plan.json output.pptx --brand my_brand.yaml
```

---

## Deck Archetypes

6 built-in archetypes define recommended slide structures for common presentation types. Pass the archetype name as `deck_type` to `plan_presentation` or `generate_presentation`.

| Archetype | Description |
|-----------|-------------|
| `pitch_deck` | Investor/stakeholder pitch with problem, solution, traction, team, and ask |
| `board_deck` | Quarterly board update with financials, strategy, and operational review |
| `sales_deck` | Customer-facing presentation with value proposition and social proof |
| `all_hands` | Company-wide update with achievements, metrics, and team recognition |
| `project_update` | Status update with progress, timeline, and risk assessment |
| `training` | Educational presentation with structured lessons and exercises |

---

## Review Engine

The review engine scores decks 0-10 and checks for design issues:

| Rule | What it checks |
|------|----------------|
| Word count | Slides exceeding max words per slide |
| Bullet count | Too many bullets on a single slide |
| Bullet length | Individual bullets that are too wordy |
| Title presence | Missing titles on non-blank slides |
| Empty slides | Slides with no content |
| Column balance | Uneven content across columns |
| Narrative flow | Missing title slide, monotonous slide types |
| Consistency | Mixed title casing across slides |
| Deck length | Over 25 slides triggers a warning |

Scoring: errors deduct 3 points, warnings 1.5, suggestions 0.5.

Example review output:

```
Score: 7.2/10.0
Issues: 5

  ERROR [slide 4] Slide has 95 words (max 60). Consider reducing text.
  WARN  [slide 6] Slide has 7 bullets (max 5).
  WARN  [deck] Presentation does not start with a title slide.
  INFO  [slide 3] Column content is significantly unbalanced.
  HINT  [slide 8] Three consecutive content slides. Consider varying layout.
```

---

## CLI Reference

```bash
# Start MCP server
pptx-mcp serve

# Generate from JSON definition
pptx-mcp generate plan.json output.pptx
pptx-mcp generate plan.json output.pptx --preset executive
pptx-mcp generate plan.json output.pptx --brand my_brand.yaml

# Plan a deck (outputs JSON)
pptx-mcp plan "Q4 Business Review" -n 10
pptx-mcp plan "Cloud Migration" -n 12 --audience executive \
  --points "Current state,Business case,Timeline,Risks" -o plan.json

# Read an existing deck
pptx-mcp read deck.pptx
pptx-mcp read deck.pptx -o parsed.json

# Review a deck
pptx-mcp review deck.pptx --preset executive

# Auto-improve a deck
pptx-mcp improve deck.pptx
pptx-mcp improve deck.pptx -o improved.pptx --preset executive
```

Run `pptx-mcp --help` for full options.

---

## Python Library

```python
from pptx_mcp.engine.generator import DeckGenerator
from pptx_mcp.engine.parser import parse_presentation
from pptx_mcp.brand.config import resolve_brand_config
from pptx_mcp.review.engine import ReviewEngine
from pptx_mcp.agents.planner import PlannerInput, SlidePlannerAgent
from pptx_mcp.models.slides import *

# Generate from a definition
brand = resolve_brand_config(preset="executive")
generator = DeckGenerator(brand=brand)
generator.generate(definition, "output.pptx")

# Plan -> Generate
planner = SlidePlannerAgent()
plan = planner.run(PlannerInput(
    topic="AI Adoption Strategy",
    audience="executive",
    num_slides=10,
    key_points=["Market opportunity", "Current capabilities", "Investment ask"],
))
generator.generate(plan, "ai_strategy.pptx")

# Read -> Review -> Improve
definition = parse_presentation("existing.pptx")
engine = ReviewEngine(brand=resolve_brand_config(preset="executive"))
review = engine.review_definition(definition)
print(f"Score: {review.overall_score}/10 -- {review.total_issues} issues")
```

---

## Project Structure

```
pptx_mcp/
  server.py               # MCP server -- 16 tools, 6 prompts, 2 resources
  cli.py                  # CLI -- serve, generate, read, review, plan, improve
  models/
    slides.py             # 23 slide types, elements, definitions
    brand.py              # BrandConfig, ColorPalette, FontConfig, SpacingConfig
    review.py             # ReviewResult, ReviewIssue, SlideReview
  engine/
    generator.py          # DeckGenerator -- renders definitions to .pptx
    parser.py             # Reads .pptx -> PresentationDefinition
    charts.py             # Bar, line, pie, column, area chart rendering
    shapes.py             # 15+ shape types, connectors
    layouts.py            # Layout renderers for all 23 slide types
    composition.py        # LayoutGrid responsive positioning system
  brand/
    config.py             # Loads YAML/JSON brand configs
    defaults.py           # 5 built-in presets
  agents/
    base.py               # BaseAgent[Input, Output] abstract class
    planner.py            # SlidePlannerAgent -- topic -> slide plan
    designer.py           # DesignAgent -- layout optimization
    reviewer.py           # ReviewAgent -- structured critique
    iterator.py           # IterationAgent -- applies review fixes
    archetypes.py         # 6 deck archetypes
  review/
    engine.py             # ReviewEngine -- scoring and summary
    rules.py              # Design rule definitions
  utils/
    logging.py            # Structured logging
    errors.py             # Typed exceptions
    paths.py              # Path validation and security
```

---

## Security

This server operates on local filesystem paths provided in tool arguments. See [SECURITY.md](SECURITY.md) for details on path validation and input handling.

---

## Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

```bash
git clone https://github.com/swak/pptx-mcp.git
cd pptx-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
```

---

## License

MIT
