pptx-mcp 0.15.0

AI-powered PowerPoint (.pptx) generation, editing, and review via MCP — 42 tools, 53 slide types, 12 chart types, 8 diagrams, 12 branded presets, 34 archetypes, 8 variant groups, image treatments (mask/duotone/overlay), proportional type-scale, dark-mode palettes, responsive aspect ratios (16:9/4:3/16:10), gradient presets, icon pack, financial primitives, and a 33-rule review engine with WCAG a11y, MECE/parallelism, data-provenance, auto-fix

PPTX MCP

AI-Powered PowerPoint Generation

Made by swak

---

What This Does

PPTX MCP is a Model Context Protocol server that lets AI assistants create, edit, and review real PowerPoint files. It produces native .pptx files with 53 slide types (including org charts, Gantt charts, 8 diagram types, SCR executive summaries, RAG scorecards, testimonials, pricing tables, logo walls, full-bleed heroes, before/after splits, references, sensitivity tables, tornado charts, risk heatmaps, and financial bridges), 12 chart types, 12 brand presets, 34 deck archetypes, and a 33-rule review engine that scores your decks across 8 categories (accessibility, brand compliance, typography, color, layout, content, narrative, whitespace) — including action-title enforcement, data-provenance checks, MECE/pyramid-principle validators, parallelism detection, deck-color-budget enforcement — and auto-fixes design issues. Ships with financial-table primitives (variance coloring, total rows, build_financial_table helper), 6 variant groups for content-preserving slide swaps, and an icon registry. 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.
• 53 slide types -- title, content, charts, tables, timelines, dashboards, SWOT, funnels, card grids, org charts, Gantt charts, executive summaries (SCR), RAG scorecards, testimonials, pricing tables, logo walls, full-bleed heroes, before/after splits, references, sensitivity tables, tornado charts, risk heatmaps, financial bridges, and more.
• 12 chart types -- bar, line, pie, column, area, scatter, bubble, radar, doughnut, stacked bar, stacked column, combo.
• 8 diagram types -- org chart, matrix, pyramid, Venn, waterfall, hub-spoke, cycle, Gantt.
• Review engine -- 33 rules across 8 categories (accessibility, brand, typography, color, layout, content, narrative, whitespace), scores decks 0-10, and auto-fixes 7 issue types. Includes executive-grade rules: action-title enforcement (pyramid principle), data-provenance checks (source citations on every chart/table/KPI), MECE bucket-count validation, title↔body word-overlap, bullet parallelism, deck color budget, and title-position consistency.
• Brand consistency -- 12 built-in presets (including industry verticals) or bring your own brand config.
• Brand extraction -- analyze an existing .pptx to extract colors, fonts, and spacing as a reusable brand config.
• Round-trip editing -- read existing decks, modify individual slides, re-render with new branding.
• Designer features -- shadow presets, edge accent bars, dividers, text auto-fit, logo placement, line dash styles.
• Deck archetypes -- 27 templates (pitch deck, board update, consulting assessments, product launch, etc.) for intelligent slide selection.
• Brand guide -- generate a 13-slide PPTX with visual specimens showcasing your brand's colors, typography, spacing, and shape styles.
• Plan cache -- server-side caching of planned decks avoids token-limit issues. Plans return compact summaries (~1-2KB) regardless of deck size.

---

Quick Start

Option 1: uvx (recommended)

Zero-install for any MCP client. Requires uv.

uvx pptx-mcp serve

Option 2: pip install

pip install pptx-mcp
pptx-mcp serve

Option 3: From source

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

claude mcp add pptx-mcp -- uvx pptx-mcp serve

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

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

Using a local install instead of uvx?

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

Claude Desktop

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

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

Using a local install instead of uvx?

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

Cursor

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

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

Windsurf

Add to your Windsurf MCP config:

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

---

What You Can Do

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

Generation

Tool	What to ask
generate_presentation	"Create a 6-slide deck on cloud migration"
plan_presentation	"Plan a 12-slide deck on AI adoption for the board"
create_from_plan	"Render the plan I just created"
create_presentation	"Render this slide definition as a PowerPoint file"
parse_spec	"Parse this markdown spec into slides"

Editing

Tool	What to ask
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"
add_speaker_notes	"Add speaker notes to slide 2"

Analysis

Tool	What to ask
read_presentation	"Read my existing deck at ~/deck.pptx"
get_plan_slide	"Show me slide 3 from the plan"
get_layout_variants	"What other layouts could slide 3 use?"
analyze_presentation	"Describe what's in this deck"
review_presentation	"Review my deck and tell me what to fix"

Improvement

Tool	What to ask
improve_presentation	"Auto-improve my deck and save a new version"
apply_brand_guidelines	"Re-style my deck using the minimal preset"
restyle_presentation	"Restyle this deck with the consulting brand"
optimize_design	"Optimize the layout of this slide plan"

Element Editing

Tool	What to ask
list_slide_elements	"Show me all shapes on slide 3"
modify_element	"Move the title up and make it bold"
add_element	"Add a text box at the bottom"
align_elements	"Align these three boxes to the left"
group_elements	"Group these shapes together"
delete_element	"Remove that text box from slide 3"
copy_element	"Copy this shape to slide 5"
ungroup_elements	"Ungroup the shapes on slide 4"
validate_slide_layout	"Check slide 2 for layout issues"

Bulk Editing

Tool	What to ask
find_and_replace	"Replace all occurrences of 'Acme' with 'Globex'"
batch_modify_elements	"Make all titles bold and blue"
reorder_slides	"Rearrange slides to: 1, 3, 2, 5, 4"
update_plan_slide	"Change slide 3 in the plan before rendering"
create_checkpoint	"Save a checkpoint before I make changes"
restore_checkpoint	"Revert to the last checkpoint"

Discovery

Tool	What to ask
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?"
generate_brand_guide	"Create a brand guide for the consulting preset"

Brand Tools

Tool	What to ask
parse_brand_guide	"Parse this markdown brand guide into a brand config"
extract_brand	"Extract the brand from my existing deck"

Workflows by deck size:

Deck size	Workflow	Why
Small (3-6 slides)	generate_presentation	Single step, fast
Medium (7-15 slides)	plan_presentation -> create_from_plan	Compact summary avoids token limits
Large (15+ slides)	plan_presentation -> create_from_plan -> update_slide/add_slide	Plan + targeted edits
Edit existing	read_presentation -> add_slide/update_slide/delete_slide	Modify individual slides
Fine-tune	list_slide_elements -> modify_element -> validate_slide_layout	Adjust individual shapes
Review loop	review_presentation -> improve_presentation	Auto-fix design issues
Markdown spec	parse_spec	Parse structured markdown into slides

---

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 get a compact summary with plan_id
2. Call create_from_plan with the plan_id 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

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

Title

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

Section

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

Section slides serve as visual dividers. They also support optional body text and bullets for context:

{
  "slide_type": "section",
  "title": "Key Findings",
  "subtitle": "Phase 1 Results",
  "body": "Our analysis revealed three critical areas for improvement.",
  "bullets": ["Process efficiency gaps", "Technology debt", "Staffing constraints"]
}

Content

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

Body text variant:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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, scatter, bubble, radar, doughnut, stacked_bar, stacked_column, combo

Table

{
  "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

{
  "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

{ "slide_type": "blank" }

Quote

{
  "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

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

Process

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "slide_type": "closing",
  "title": "Thank You",
  "subtitle": "Questions? Let's connect.",
  "cta_text": "Schedule a Demo",
  "contact_info": ["[e-mail]", "[phone]"]
}

SWOT

{
  "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

{
  "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

{
  "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" }
  ]
}

Card Grid

{
  "slide_type": "card_grid",
  "title": "Our Services",
  "cards": [
    {
      "title": "Strategy",
      "icon": "target",
      "body": "End-to-end strategic advisory",
      "bullets": ["Market analysis", "Growth planning"],
      "badge": { "text": "NEW" }
    },
    {
      "title": "Implementation",
      "icon": "wrench",
      "body": "Hands-on delivery and execution",
      "bullets": ["Agile delivery", "Change management"]
    },
    {
      "title": "Analytics",
      "icon": "chart",
      "body": "Data-driven insights and reporting",
      "bullets": ["Dashboards", "Predictive models"]
    }
  ]
}

Each card supports title, icon, body, bullets, and an optional badge with text and color. Supports 2-12 cards in an auto-grid layout.

Org Chart

{
  "slide_type": "org_chart",
  "title": "Organization Structure",
  "org_nodes": {
    "name": "CEO",
    "title": "Jane Smith",
    "children": [
      { "name": "VP Engineering", "title": "John Doe", "children": [
        { "name": "Team Lead", "title": "Alice" },
        { "name": "Team Lead", "title": "Bob" }
      ]},
      { "name": "VP Product", "title": "Carol White" }
    ]
  }
}

Uses Buchheim tree layout for automatic node positioning.

Matrix

{
  "slide_type": "matrix",
  "title": "Priority Matrix",
  "matrix_data": {
    "x_axis_label": "Effort",
    "y_axis_label": "Impact",
    "quadrant_labels": ["Quick Wins", "Major Projects", "Fill-Ins", "Thankless Tasks"],
    "items": [
      { "label": "Feature A", "x": 0.2, "y": 0.8 },
      { "label": "Feature B", "x": 0.7, "y": 0.9 }
    ]
  }
}

Pyramid

{
  "slide_type": "pyramid",
  "title": "Strategic Priorities",
  "pyramid_layers": [
    { "label": "Vision", "description": "Long-term direction" },
    { "label": "Strategy", "description": "How we get there" },
    { "label": "Execution", "description": "Day-to-day operations" }
  ]
}

Venn

{
  "slide_type": "venn",
  "title": "Market Overlap",
  "venn_data": {
    "circles": [
      { "label": "Enterprise", "description": "Large orgs" },
      { "label": "Mid-Market", "description": "Growth companies" },
      { "label": "SMB", "description": "Small teams" }
    ],
    "intersection_label": "Our ICP"
  }
}

Waterfall

{
  "slide_type": "waterfall",
  "title": "Revenue Bridge",
  "waterfall_bars": [
    { "label": "Starting", "value": 100, "bar_type": "total" },
    { "label": "New Sales", "value": 40, "bar_type": "increase" },
    { "label": "Churn", "value": -15, "bar_type": "decrease" },
    { "label": "Ending", "value": 125, "bar_type": "total" }
  ]
}

Hub & Spoke

{
  "slide_type": "hub_spoke",
  "title": "Platform Ecosystem",
  "hub_label": "Core Platform",
  "spoke_items": [
    { "label": "API", "description": "Developer access" },
    { "label": "Analytics", "description": "Insights engine" },
    { "label": "Auth", "description": "Identity management" },
    { "label": "Storage", "description": "Data layer" }
  ]
}

Cycle

{
  "slide_type": "cycle",
  "title": "Development Lifecycle",
  "cycle_steps": [
    { "label": "Plan", "description": "Define requirements" },
    { "label": "Build", "description": "Implement features" },
    { "label": "Test", "description": "Validate quality" },
    { "label": "Deploy", "description": "Release to production" },
    { "label": "Monitor", "description": "Track performance" }
  ]
}

Gantt

{
  "slide_type": "gantt",
  "title": "Project Timeline",
  "gantt_tasks": [
    { "label": "Research", "start": 0, "duration": 3, "progress": 1.0 },
    { "label": "Design", "start": 2, "duration": 4, "progress": 0.5 },
    { "label": "Development", "start": 5, "duration": 6, "progress": 0.0 },
    { "label": "Testing", "start": 10, "duration": 2, "progress": 0.0 }
  ],
  "gantt_unit": "weeks"
}

Speaker Notes

Any slide type supports speaker notes:

{
  "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	Aptos
technical	Dark, teal accents	#263238	#00BCD4	Segoe UI
minimal	High-contrast B&W	#111111	#FF4444	Arial
creative	Bold, colorful	#6B21A8	#F59E0B	Georgia / Aptos
corporate	Conservative, formal	#1E3A5F	#C9A84C	Garamond / Aptos
consulting	Professional, structured	#1A3C6E	#D4A843	Aptos
healthcare	Clean, trustworthy	#0D6EAE	#27AE60	Aptos
startup	Bold, modern	#6C5CE7	#00D2D3	Aptos Display
academic	Scholarly, structured	#800020	#DAA520	Garamond / Aptos
government	Formal, accessible	#003366	#CC0000	Aptos
finance	Sophisticated, precise	#1A3C34	#B8860B	Aptos Display
nonprofit	Warm, approachable	#E07C3E	#2E86AB	Aptos Display

The consulting and finance presets include confidential markings. The consulting, government, healthcare, and finance presets include slide numbers and date footers. The startup preset features a left edge bar; consulting uses medium shadow presets; minimal enables dividers and text auto-fit.

Generate a brand guide PPTX for any preset with generate_brand_guide. Extract a brand config from an existing deck with extract_brand.

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

Custom Brand Config

Create a YAML file:

name: "Your Company"

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

fonts:
  heading_font: "Arial"
  body_font: "Arial"
  display_font: "Impact"
  title_size: 36
  heading_size: 28
  body_size: 16
  display_size: 44
  font_weight_heading: "Bold"
  font_weight_body: "Regular"
  paragraph_spacing: 6.0

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

shape_style:
  card_corner_radius: 0.08
  shadow_preset: "subtle"        # none | subtle | medium | elevated
  edge_bar: "left"               # none | left | top
  edge_bar_width: 0.15
  divider_style: "thin_line"     # none | thin_line | dotted
  line_dash_style: "solid"       # solid | dash | dot | dash_dot | long_dash
  text_auto_fit: true

logo:
  path: "/path/to/logo.png"
  placement: "top_left"          # top_left | top_right | bottom_left | bottom_right
  max_height: 0.5
  skip_on: ["title", "closing"]

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:

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

Brand from Markdown

Use the parse_brand_guide tool with markdown:

# My Brand

## Colors
- primary: #002B5C
- secondary: #0066CC
- accent: #FF6B00

## Typography
- heading_font: Arial
- body_font: Arial
- title_size: 36

## Shape Style
- shadow_preset: medium
- edge_bar: left

Brand from Existing Deck

Use the extract_brand tool to analyze a .pptx and extract its colors, fonts, and spacing as a reusable brand config:

"Extract the brand from my_deck.pptx and save it to my_brand.json"

---

Deck Archetypes

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

General

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
product_launch	Product launch with features, competitive edge, and rollout schedule
case_study	Customer success story with challenge, approach, results, and testimonial
quarterly_earnings	Quarterly financial report with highlights, trends, and guidance
onboarding	New hire/client onboarding with values, timeline, and key contacts
annual_report	Year-in-review with KPIs, milestones, leadership, and year-ahead outlook
conference_talk	Keynote/conference presentation with big ideas and takeaways

Consulting

Archetype	Description
strategy_deck	Strategic planning with market analysis, competitive landscape, and recommendations
due_diligence	Investment analysis with financials, risks, and deal assessment
market_analysis	Market sizing, segmentation, trends, and competitive positioning
org_design	Organizational restructuring with current/future state and implementation plan
competitive_assessment	Competitor landscape, SWOT analysis, and strategic positioning
transformation_roadmap	Change management with phased implementation and success metrics
assessment	General assessment/audit with findings, matrix, and remediation plan
opportunity_assessment	Opportunity sizing with pipeline, scenarios, and investment recommendation
strategy_training	Consulting methodology training with frameworks and case application
template_guide	How-to-use guide for templates, systems, or workflows
executive_overview	High-level executive briefing with key metrics and strategic focus
analysis_deck	Data-driven analytical deep-dive with trends and scenario modeling
cost_breakdown	Cost/revenue breakdown with line items, benchmarks, and optimization
architecture_review	IT/systems architecture review with components and migration roadmap
analytics_dashboard	Data analytics presentation with KPIs, charts, and key insights

---

Review Engine

The review engine scores decks 0-10 with 33 rules across 8 categories. It auto-fixes deterministic issues (title casing, minimum font sizes, off-brand colors) and flags the rest for manual review.

Content & Layout (definition-level)

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
Card count	Too many cards (>6) or KPIs (>8)
Shadow + border conflict	Thick borders combined with shadow presets

Narrative & Consistency (deck-level)

Rule	What it checks
Narrative flow	Missing title slide, monotonous slide types, deck length
Consistency	Mixed title casing across slides
Visual rhythm	3+ consecutive slides of the same type

Spatial Validation (PPTX-level)

Rule	What it checks
Element overlap	Shapes overlapping by more than 0.05"
Element bounds	Shapes extending beyond slide edges
Element spacing	Shapes closer than 0.1" apart
Text overflow	Text likely overflowing its container
Whitespace ratio	Slide >85% covered (crowded) or <15% (sparse)

Accessibility

Rule	What it checks
Image alt text	Images missing alt text descriptions
Min font size	Text runs below brand minimum font size
Contrast ratio	WCAG text-to-background contrast (4.5:1 body, 3.0:1 large text)

Brand Compliance

Rule	What it checks
Font compliance	Fonts not in the brand font set
Color compliance	Colors far from the brand palette (distance >50)
Logo presence	Brand logo configured but missing from title slide
Chart brand colors	Charts present but no chart_colors defined

Typography & Color

Rule	What it checks
Font hierarchy	Title > heading > body > caption sizes not strictly decreasing
Font family count	More than 3 distinct font families per slide
Accent overuse	More than 2 elements using the accent color
Distinct color count	More than 5 non-neutral colors per slide

Auto-fix patterns (applied by improve_presentation):

Fix	Trigger
Split bullets to columns	>6 bullets on a content slide
Promote first bullet	Missing title on content slide
Rebalance columns	Significantly unbalanced column content
Remove empty slides	Slides with no content
Normalize title casing	Inconsistent title casing across deck
Bump minimum font size	Text below brand minimum
Snap off-brand colors	Fill colors far from brand palette

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

Example review output:

Score: 7.2/10.0
Issues: 8

  ERROR [slide 4] Slide has 95 words (max 60). Consider reducing text.
  WARN  [slide 6] Slide has 7 bullets (max 5).
  WARN  [slide 2] 3 text run(s) below minimum font size (12pt).
  WARN  [slide 5] Low contrast (2.1:1) on 'Content Box' (threshold 4.5:1).
  INFO  [slide 3] Off-brand font(s): Comic Sans MS.
  INFO  [slide 7] Accent color used on 4 elements; sparingly is preferred.
  HINT  [deck] Slides 3-5 are all content; vary layout for visual rhythm.
  HINT  [slide 1] Image missing alt text description for accessibility.

---

Token Limit Guidance

Large presentation plans (10+ slides) can produce 13-16KB of JSON, which may exceed LLM output token limits. PPTX MCP solves this with server-side plan caching:

1. plan_presentation caches the full definition server-side and returns a compact summary (~1-2KB) with a plan_id
2. create_from_plan renders the cached plan to .pptx without transferring the full definition
3. get_plan_slide retrieves individual slides (~0.5-1.5KB each) for inspection

Plans are cached for 1 hour (max 50 concurrent plans). For backward compatibility, pass return_full_json=True to plan_presentation to get the full definition.

---

Markdown Spec Format

The parse_spec tool accepts structured markdown that describes slide content. This lets you write presentations in markdown and convert them to .pptx.

# Presentation Title
subtitle: Q4 2025 Review
author: Jane Smith

---

## Market Analysis
- Revenue grew 15% YoY
- Customer retention at 92%
- NPS improved from 54 to 67

---

## Financial Dashboard
| Metric | Value | Change |
|--------|-------|--------|
| Revenue | $14M | +15% |
| Margin | 42% | +3pp |
| Headcount | 124 | +18 |

---

## Key Quote
> "The best way to predict the future is to create it."
> — Peter Drucker

Supported elements: headers (##), bullet lists (-), tables (|), blockquotes (>), code blocks, and color tokens (color: #FF6B00). Slide types are auto-detected from content structure.

---

CLI Reference

# 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

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 -- 42 tools, 9 prompts, 2 resources
  cli.py                  # CLI -- serve, generate, read, review, plan, improve
  models/
    slides.py             # 53 slide types, 12 chart types, elements, definitions
    brand.py              # BrandConfig, LogoConfig, ColorPalette, FontConfig, ShapeStyleConfig
    diagrams.py           # OrgNode, MatrixData, PyramidLayer, VennData, and more
    review.py             # ReviewResult, ReviewIssue, SlideReview
    editor.py             # ElementLocator, ElementModification, ElementInfo
  engine/
    generator.py          # DeckGenerator -- renders definitions to .pptx
    parser.py             # Reads .pptx -> PresentationDefinition
    spec_parser.py        # Markdown spec -> PresentationDefinition + parse_brand_guide
    describer.py          # Natural-language slide/deck descriptions
    charts.py             # 12 chart types (bar, scatter, bubble, radar, combo, etc.)
    shapes.py             # 15+ shape types, connectors, shadow/dash/color helpers
    layouts.py            # Layout renderers for all slide types + edge bars, dividers
    composition.py        # LayoutGrid responsive positioning system
    editor.py             # Element-level editing (list, modify, add, align, group, delete, copy, find/replace, batch, reorder)
    brand_guide.py        # 13-slide brand guide with visual specimens
    brand_extractor.py    # Extract BrandConfig from existing .pptx
    diagrams/             # 8 diagram renderers (org chart, matrix, pyramid, etc.)
  brand/
    config.py             # Loads YAML/JSON brand configs
    defaults.py           # 12 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 (7 auto-fix patterns)
    archetypes.py         # 34 deck archetypes
    content_mapper.py     # Keyword -> SlideType suggestions
  review/
    engine.py             # ReviewEngine -- scoring and summary
    rules.py              # 15 design rules (content, layout, narrative, accessibility, brand, color, typography)
    spatial.py            # 11 spatial rules (overlap, bounds, spacing, text overflow, contrast, font/color compliance, whitespace)
  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 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.

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