📊 PPTX MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to create, edit, and manipulate PowerPoint presentations programmatically.

✨ Features

Full PowerPoint Control - Create, read, and modify .pptx files without needing PowerPoint installed
AI-Native Design - Built specifically for LLMs to generate and edit presentations through structured JSON
Rich Formatting Support - Text styling, colors, alignment, bullets, shapes, and backgrounds
Template Workflows - Extract content from existing presentations, modify, and regenerate
Visual Debugging - Generate thumbnail grids to preview slides programmatically
Office XML Access - Direct access to underlying OOXML for advanced customization

🚀 Quick Start

1. Install

# Clone the repository
git clone https://github.com/YOUR_USERNAME/pptx-mcp-server.git
cd pptx-mcp-server

# Install the package
pip install -e .

2. Configure Your MCP Client

Add to your MCP settings:

Claude Desktop

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

{
  "mcpServers": {
    "pptx": {
      "command": "python",
      "args": ["-m", "pptx_mcp_server"]
    }
  }
}

Cursor

Add to your MCP configuration:

{
  "mcpServers": {
    "pptx": {
      "command": "python",
      "args": ["-m", "pptx_mcp_server"]
    }
  }
}

Using a Virtual Environment (conda/venv)

Specify the full path to your Python interpreter:

{
  "mcpServers": {
    "pptx": {
      "command": "/path/to/your/python",
      "args": ["-m", "pptx_mcp_server"]
    }
  }
}

Examples:

Conda: /Users/username/miniconda3/bin/python
venv: /path/to/project/.venv/bin/python

3. Restart Your MCP Client

Restart Claude Desktop, Cursor, or your MCP client to load the server.

📦 Requirements

Python 3.10+
Dependencies (installed automatically):
- mcp - Model Context Protocol SDK
- python-pptx - PowerPoint file manipulation
- Pillow - Image processing
- lxml - XML parsing
- defusedxml - Secure XML parsing

Optional (for thumbnails)

# macOS
brew install --cask libreoffice
brew install poppler

# Ubuntu/Debian
sudo apt-get install libreoffice poppler-utils

🛠️ Available Tools

Tool	Description
`create_presentation`	Create new presentations from scratch
`extract_text_inventory`	Extract text content with positions and formatting
`apply_text_replacements`	Replace text using JSON specifications
`rearrange_slides`	Duplicate, delete, and reorder slides
`create_thumbnail_grid`	Generate visual thumbnail grids
`unpack_office_document`	Extract Office files to editable XML
`pack_office_document`	Rebuild Office files from XML
`validate_office_document`	Validate document structure

📖 Usage Examples

Create a New Presentation

{
  "output_path": "/path/to/presentation.pptx",
  "layout": "16:9",
  "slides": [
    {
      "background": "#0f172a",
      "shapes": [
        {
          "type": "textbox",
          "left": 0.5,
          "top": 3,
          "width": 12,
          "height": 1.5,
          "text": "Welcome to My Presentation",
          "font_size": 54,
          "bold": true,
          "color": "#ffffff",
          "alignment": "center"
        },
        {
          "type": "textbox",
          "left": 0.5,
          "top": 5,
          "width": 12,
          "height": 1,
          "text": "Subtitle goes here",
          "font_size": 24,
          "color": "#94a3b8",
          "alignment": "center"
        }
      ]
    },
    {
      "shapes": [
        {
          "type": "textbox",
          "left": 0.5,
          "top": 0.5,
          "width": 12,
          "height": 1,
          "text": "Key Points",
          "font_size": 36,
          "bold": true
        },
        {
          "type": "textbox",
          "left": 0.5,
          "top": 1.8,
          "width": 12,
          "height": 5,
          "paragraphs": [
            {"text": "First important point", "font_size": 24, "bullet": true},
            {"text": "Second important point", "font_size": 24, "bullet": true},
            {"text": "Third important point", "font_size": 24, "bullet": true}
          ]
        }
      ]
    }
  ]
}

Supported shape types:

textbox - Text content
rectangle - Rectangle (can contain text)
rounded_rectangle - Rounded corners
oval - Circle/ellipse
image - Image file (use path property)
line - Line connector

Supported layouts: 16:9, 4:3, widescreen, standard

Extract Text Inventory

Get all text content from an existing presentation:

{
  "pptx_path": "/path/to/presentation.pptx"
}

Returns structured JSON:

{
  "slide-0": {
    "shape-0": {
      "left": 0.5,
      "top": 1.0,
      "width": 12.0,
      "height": 1.5,
      "paragraphs": [
        {"text": "Title Text", "font_size": 44.0, "bold": true}
      ]
    }
  }
}

Replace Text Content

Modify text in an existing presentation:

{
  "pptx_path": "/path/to/template.pptx",
  "output_path": "/path/to/output.pptx",
  "replacements_json": {
    "slide-0": {
      "shape-0": [
        {"text": "New Title", "font_size": 44, "bold": true}
      ]
    }
  }
}

Rearrange Slides

Reorder, duplicate, or remove slides:

{
  "template_path": "/path/to/template.pptx",
  "output_path": "/path/to/output.pptx",
  "slide_sequence": "0,2,2,1,3"
}

0,2,2,1,3 → Keep slide 0, duplicate slide 2, then slides 1 and 3
Omit an index to delete that slide

Unpack/Pack for XML Editing

// Unpack to directory
{
  "office_file": "/path/to/document.pptx",
  "output_dir": "/path/to/unpacked"
}

// Pack back to file
{
  "input_dir": "/path/to/unpacked",
  "output_file": "/path/to/output.pptx"
}

🔧 Troubleshooting

ModuleNotFoundError: No module named 'mcp'

Ensure you're using the correct Python environment:

# Check which Python pip uses
pip --version

# Install with specific Python
/path/to/python -m pip install -e .

Server not appearing in MCP client

Verify the config file path is correct for your OS
Ensure JSON syntax is valid (no trailing commas)
Restart the MCP client completely
Check logs for errors

Thumbnail generation fails

Install LibreOffice and poppler:

# macOS
brew install --cask libreoffice && brew install poppler

# Linux
sudo apt-get install libreoffice poppler-utils

Permission denied errors

Ensure the output paths are writable and parent directories exist.

📁 Project Structure

pptx-mcp-server/
├── pyproject.toml              # Package configuration
├── README.md
└── pptx_mcp_server/
    ├── __init__.py
    ├── server.py               # MCP server implementation
    └── tools/
        ├── __init__.py
        ├── create.py           # Create new presentations
        ├── inventory.py        # Extract text content
        ├── replace.py          # Text replacement
        ├── rearrange.py        # Slide manipulation
        ├── thumbnail.py        # Visual thumbnails
        └── ooxml.py            # XML pack/unpack/validate

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

🙏 Acknowledgments

Built with python-pptx
Uses the Model Context Protocol by Anthropic