pptx-creator-mcp 0.1.0

An MCP server for creating, analyzing, and rendering professional PPTX presentations programmatically.

pptx-creator-mcp

A Model Context Protocol (MCP) server for creating, analyzing, and rendering professional PowerPoint (PPTX) presentations. Built on FastMCP and python-pptx.

Presentations are generated with a dark gradient executive theme, structured slide types, and inline rich-text styling -- ready for boardroom use without manual formatting.

---

Table of Contents

• Overview
• Features
• Requirements
• Installation
• Quick Start
• MCP Client Configuration
• Tools Reference
  • create_presentation
  • analyze_presentation
  • render_slide_screenshots
• Slide Types
• Inline Styling
• Backgrounds
• Theme Reference
• Examples
• License

---

Overview

pptx-creator-mcp exposes three MCP tools that allow AI agents and automation pipelines to generate, inspect, and render PowerPoint presentations without manual intervention. It accepts structured JSON slide data and produces fully formatted .pptx files with dark gradient backgrounds, metric cards, data tables, bar charts, multi-column layouts, and inline styling.

---

Features

• 10 slide types: title, content, metrics, table, quote, two_column, three_column, bars, summary, image.
• Dark executive theme with diagonal gradient backgrounds, card-based layouts, and professional typography.
• Inline rich-text styling via <style> tags with support for color, font size, font family, bold, italic, and underline.
• Presentation analysis that extracts shape-level styling, background properties, text formatting (including theme-inherited styles), table cell styling, and a global color/font palette.
• Slide rendering to PNG images via LibreOffice headless, PowerPoint COM (Windows), or a pure-Python Pillow fallback.
• Image embedding from local file paths or URLs with automatic aspect-ratio preservation.
• Background customization via presets or custom gradient color pairs, with support for background images.
• Automatic low-confidence screenshots during analysis for slides where programmatic extraction is insufficient.

---

Requirements

• Python 3.10 or later
• For PNG rendering (optional): LibreOffice installed, or pdf2image with Poppler

---

Installation

From PyPI

pip install pptx-creator-mcp

With PDF rendering support

pip install pptx-creator-mcp[pdf]

From source

git clone https://github.com/harmandatta/pptx-creator-mcp.git
cd pptx-creator-mcp
pip install -e .

---

Quick Start

Run the MCP server:

pptx-creator-mcp

Or run as a Python module:

python -m pptx_creator_mcp.server

---

MCP Client Configuration

Kiro

Add to .kiro/settings/mcp.json:

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

Claude Desktop

Add to your Claude Desktop MCP configuration:

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

Using uvx (no install required)

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

---

Tools Reference

create_presentation

Creates a PPTX file from an ordered list of slide objects.

Parameters:

Parameter	Type	Required	Description
slides	list[dict]	Yes	Ordered list of slide objects. Each must include a type field.
output_dir	str	Yes	Directory where the file will be saved. A generated-pptx subdirectory is created automatically.
filename	str	No	Output filename. Defaults to presentation.pptx.

Returns: Absolute path to the generated PPTX file.

---

analyze_presentation

Extracts a complete shape-level style library from an existing PPTX file.

Parameters:

Parameter	Type	Required	Description
pptx_path	str	Yes	Absolute path to the PPTX file.
auto_screenshot	bool	No	Render PNG screenshots for slides with extraction confidence below 60%. Defaults to true.

Returns: JSON string containing:

• slide_dimensions -- Width and height in inches.
• global_palette -- Most-used colors, fonts, and font sizes across all slides.
• slide_templates -- Per-slide array with background, shapes (position, fill, line, text runs with styles), confidence score, and screenshot path.
• overall_confidence_pct -- Average confidence across all slides.
• slides_needing_screenshot -- Slide indices where extraction was insufficient.
• screenshots -- Rendered screenshot info (slide index, image path, backend).

---

render_slide_screenshots

Renders PPTX slides as PNG images for visual inspection.

Parameters:

Parameter	Type	Required	Description
pptx_path	str	Yes	Absolute path to the PPTX file.
slide_indices	list[int]	No	0-based slide indices to render. Defaults to all slides.
output_dir	str	No	Directory to save PNGs. Defaults to a screenshots folder next to the file.
width	int	No	Output image width in pixels. Defaults to 1920. Height is auto-calculated.

Returns: JSON with a list of rendered slides, each containing slide_index, image_path, and backend.

Rendering backends (tried in order):

1. LibreOffice headless (macOS, Linux, Windows)
2. PowerPoint COM automation (Windows only)
3. Pure-Python fallback using Pillow and python-pptx

---

Slide Types

Each slide in the slides list must include a type field. All slide types support the following common fields:

Field	Type	Description
background	str	Background preset: bg_dark, bg_accent, bg_highlight, bg_impact.
background_colors	list[str]	Custom gradient as ["hex1", "hex2"], overriding the preset.
background_image	str	Local file path to an image used as slide background (stretched to fill).
section_label	str	Small uppercase label above the title (e.g., "THE CONTEXT").

---

title

Cover or title slide.

{
  "type": "title",
  "title": "Q3 Strategic Review",
  "subtitle": "Prepared for the Executive Committee",
  "footer": "Acme Corp | Confidential | October 2026"
}

Field	Type	Description
title	str	Main title text.
subtitle	str	Subtitle text.
footer	str	Footer text.

content

Bullet point slide with optional inline image.

{
  "type": "content",
  "title": "Key Findings",
  "bullets": ["Revenue up 12%", "Costs reduced by 8%", "Market share grew 3pp"],
  "footer_text": "Source: Internal analytics"
}

Field	Type	Description
title	str	Slide title.
bullets	list[str]	Bullet point items. Each supports <style> tags.
footer_text	str	Bottom text.
image_path	str	Optional image placed below bullets.

metrics

Big number cards (up to 3).

{
  "type": "metrics",
  "title": "Financial Highlights",
  "metrics": [
    { "value": "$4.2B", "label": "Revenue", "color": "color_green" },
    { "value": "18%", "label": "Growth", "color": "color_accent" },
    { "value": "$890M", "label": "EBITDA", "description": "Up 22% YoY" }
  ]
}

Field	Type	Description
title	str	Slide title.
metrics	list[dict]	Each: value, label, optional description, optional color (hex or theme key).

Theme color keys: color_accent, color_green, color_orange, color_red.

table

Data table with optional row highlighting.

{
  "type": "table",
  "title": "Regional Performance",
  "headers": ["Region", "Revenue", "Growth"],
  "rows": [
    ["North America", "$2.1B", "+15%"],
    ["Europe", "$1.4B", "+8%"],
    ["Asia Pacific", "$0.7B", "+22%"]
  ],
  "highlight_rows": [2]
}

Field	Type	Description
title	str	Slide title.
headers	list[str]	Column header labels.
rows	list[list]	Row data. Each inner list is one row.
highlight_rows	list[int]	0-based row indices to highlight in green.

quote

Quote with attribution.

{
  "type": "quote",
  "title": "Customer Voice",
  "quote": "This platform reduced our forecasting error by 40%.",
  "attribution": "-- VP Supply Chain, Fortune 500 CPG"
}

Field	Type	Description
title	str	Slide title.
quote	str	Quote text.
attribution	str	Source attribution.

two_column

Two-column layout with optional card backgrounds and images.

{
  "type": "two_column",
  "title": "Current vs. Future State",
  "left": {
    "title": "Today",
    "items": ["Manual processes", "Siloed data", "Reactive decisions"],
    "card": true
  },
  "right": {
    "title": "Tomorrow",
    "items": ["Automated pipelines", "Unified data lake", "Predictive insights"],
    "card": true
  }
}

Each column supports:

Field	Type	Description
title	str	Column heading.
text	str	Body text.
items	list[str]	Bullet items.
card	bool	Render a card background behind the column.
image_path	str	Image displayed in the column.

three_column

Three card columns with accent borders.

{
  "type": "three_column",
  "title": "Strategic Pillars",
  "columns": [
    { "title": "Efficiency", "text": "Reduce operational costs by 15%", "accent_color": "66BB6A" },
    { "title": "Growth", "text": "Expand into 3 new markets", "accent_color": "4FC3F7" },
    { "title": "Innovation", "text": "Launch AI-powered forecasting", "accent_color": "FFA726" }
  ]
}

Each column supports:

Field	Type	Description
title	str	Card heading.
subtitle	str	Optional subtitle.
text	str	Card body text.
footer	str	Card footer text.
accent_color	str	Top border accent color (hex or theme key).

bars

Horizontal bar chart.

{
  "type": "bars",
  "title": "Market Share by Region",
  "bars": [
    { "label": "North America", "value": 42, "display_value": "42%" },
    { "label": "Europe", "value": 28, "display_value": "28%" },
    { "label": "Asia Pacific", "value": 18, "display_value": "18%" }
  ]
}

Field	Type	Description
title	str	Slide title.
bars	list[dict]	Each: label, value (numeric), display_value (str), optional color.

summary

Summary slide with a row of compact metric cards.

{
  "type": "summary",
  "title": "Projected annual impact across all workstreams",
  "metrics": [
    { "value": "$120M", "label": "Cost Savings" },
    { "value": "3.2x", "label": "ROI" },
    { "value": "18mo", "label": "Payback" }
  ]
}

Field	Type	Description
title	str	Main summary text.
metrics	list[dict]	Each: value, label, optional color.
footer_text	str	Bottom text.

image

Dedicated image slide with centered or full-bleed modes.

{
  "type": "image",
  "image_path": "/path/to/architecture.png",
  "title": "System Architecture",
  "caption": "Figure 1: End-to-end data flow",
  "image_mode": "centered"
}

Field	Type	Default	Description
image_path	str	--	Local file path or URL (required).
title	str	--	Optional title above or over the image.
caption	str	--	Optional caption below the image.
image_mode	str	"centered"	"centered" or "full" (stretches to fill).

---

Inline Styling

Any text field in any slide type supports inline <style> tags for granular formatting control.

Syntax:

Unlock <style color="green" text-size="36" bold="true">$6.5B</style> in annual savings

Supported attributes:

Attribute	Type	Description
color	str	CSS color name (red, green, blue, orange, accent, muted) or hex (#FF5733).
text-size	number	Font size in points.
font-type	str	Font family name (e.g., Arial, Segoe UI).
bold	bool	true or false.
italic	bool	true or false.
underline	bool	true or false.

Named colors:

white, black, red, green, blue, orange, yellow, purple, cyan, gray, lightgray, darkgray, accent, muted, subtle

---

Backgrounds

Presets

Key	Gradient	Use case
bg_dark	0A0A0A to 1A1A2E	Default, title slides.
bg_accent	1A1A2E to 16213E	Content, metrics slides.
bg_highlight	0F3460 to 1A1A2E	Emphasis slides.
bg_impact	1A1A2E to 0A3D2E	Impact/results slides.

Custom gradients

{ "background_colors": ["0D1117", "161B22"] }

Background images

{ "background_image": "/path/to/image.jpg" }

When background_image is set, it overrides both background and background_colors.

---

Theme Reference

The default theme uses the following values. These are applied automatically and can be referenced in metric color fields using their key names.

Key	Hex Value	Usage
color_title	F0F0F0	Slide titles.
color_body	CCCCCC	Body text.
color_accent	4FC3F7	Accent elements, links.
color_green	66BB6A	Positive metrics, highlights.
color_orange	FFA726	Warnings, callouts.
color_red	EF5350	Negative metrics, alerts.
color_muted	888888	Footers, captions.
color_section_label	A0C4FF	Section labels.

Fonts: Segoe UI for both headings and body text. Slide dimensions: 13.333 x 7.5 inches (widescreen 16:9).

---

Examples

Minimal presentation

{
  "slides": [
    {
      "type": "title",
      "title": "Quarterly Business Review",
      "subtitle": "Q3 2026",
      "footer": "Acme Corp | Confidential"
    },
    {
      "type": "content",
      "title": "Agenda",
      "bullets": ["Financial overview", "Operational highlights", "Strategic priorities"]
    }
  ],
  "output_dir": "/tmp",
  "filename": "qbr.pptx"
}

Executive pitch deck

{
  "slides": [
    {
      "type": "title",
      "title": "AI-Powered Supply Chain",
      "subtitle": "Transforming demand forecasting with machine learning"
    },
    {
      "type": "metrics",
      "section_label": "THE OPPORTUNITY",
      "title": "Projected Impact",
      "metrics": [
        { "value": "$120M", "label": "Annual Savings", "color": "color_green" },
        { "value": "40%", "label": "Forecast Error Reduction", "color": "color_accent" },
        { "value": "3.2x", "label": "ROI", "description": "Over 3 years" }
      ]
    },
    {
      "type": "two_column",
      "title": "Current vs. Future State",
      "left": {
        "title": "Today",
        "items": ["Manual spreadsheet forecasts", "7-day planning cycles", "15% average error rate"],
        "card": true
      },
      "right": {
        "title": "With AI/ML",
        "items": ["Automated ML predictions", "Real-time adjustments", "5% average error rate"],
        "card": true
      }
    },
    {
      "type": "table",
      "section_label": "FINANCIAL DETAIL",
      "title": "Three-Year Cost Projection",
      "headers": ["Category", "Year 1", "Year 2", "Year 3"],
      "rows": [
        ["Infrastructure", "$2.4M", "$1.8M", "$1.5M"],
        ["Services", "$1.2M", "$0.6M", "$0.3M"],
        ["Savings", "$8M", "$45M", "$67M"]
      ],
      "highlight_rows": [2]
    },
    {
      "type": "summary",
      "title": "Projected annual impact across all workstreams",
      "metrics": [
        { "value": "$120M", "label": "Savings" },
        { "value": "3.2x", "label": "ROI" },
        { "value": "18mo", "label": "Payback" }
      ],
      "footer_text": "Based on conservative estimates validated with finance team"
    }
  ],
  "output_dir": "/tmp",
  "filename": "ai_supply_chain_pitch.pptx"
}

---

License

This project is licensed under the MIT License. See LICENSE for details.