Metadata-Version: 2.4
Name: pptx-creator-mcp
Version: 0.1.0
Summary: An MCP server for creating, analyzing, and rendering professional PPTX presentations programmatically.
Project-URL: Homepage, https://pypi.org/project/pptx-creator-mcp/
Project-URL: Issues, https://github.com/harmandatta/pptx-creator-mcp/issues
Author: Harman Datta
License-Expression: MIT
License-File: LICENSE
Keywords: fastmcp,mcp,model-context-protocol,powerpoint,pptx,presentation,slide-generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: lxml>=4.9.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-pptx>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: pdf
Requires-Dist: pdf2image>=1.16.0; extra == 'pdf'
Description-Content-Type: text/markdown

# pptx-creator-mcp

A Model Context Protocol (MCP) server for creating, analyzing, and rendering professional PowerPoint (PPTX) presentations. Built on [FastMCP](https://github.com/jlowin/fastmcp) and [python-pptx](https://python-pptx.readthedocs.io/).

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](#overview)
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [MCP Client Configuration](#mcp-client-configuration)
- [Tools Reference](#tools-reference)
  - [create_presentation](#create_presentation)
  - [analyze_presentation](#analyze_presentation)
  - [render_slide_screenshots](#render_slide_screenshots)
- [Slide Types](#slide-types)
- [Inline Styling](#inline-styling)
- [Backgrounds](#backgrounds)
- [Theme Reference](#theme-reference)
- [Examples](#examples)
- [License](#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

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

### With PDF rendering support

```bash
pip install pptx-creator-mcp[pdf]
```

### From source

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

---

## Quick Start

Run the MCP server:

```bash
pptx-creator-mcp
```

Or run as a Python module:

```bash
python -m pptx_creator_mcp.server
```

---

## MCP Client Configuration

### Kiro

Add to `.kiro/settings/mcp.json`:

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

### Claude Desktop

Add to your Claude Desktop MCP configuration:

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

### Using uvx (no install required)

```json
{
  "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.

```json
{
  "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.

```json
{
  "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).

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

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

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

### Background images

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

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

```json
{
  "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](LICENSE) for details.
