# 📊 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

```bash
# 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:

<details>
<summary><b>Claude Desktop</b></summary>

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

```json
{
  "mcpServers": {
    "pptx": {
      "command": "python",
      "args": ["-m", "pptx_mcp_server"]
    }
  }
}
```
</details>

<details>
<summary><b>Cursor</b></summary>

Add to your MCP configuration:

```json
{
  "mcpServers": {
    "pptx": {
      "command": "python",
      "args": ["-m", "pptx_mcp_server"]
    }
  }
}
```
</details>

<details>
<summary><b>Using a Virtual Environment (conda/venv)</b></summary>

Specify the full path to your Python interpreter:

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

### 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)

```bash
# 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

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

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

Returns structured JSON:
```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:

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

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

```json
// 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

<details>
<summary><b>ModuleNotFoundError: No module named 'mcp'</b></summary>

Ensure you're using the correct Python environment:

```bash
# Check which Python pip uses
pip --version

# Install with specific Python
/path/to/python -m pip install -e .
```
</details>

<details>
<summary><b>Server not appearing in MCP client</b></summary>

1. Verify the config file path is correct for your OS
2. Ensure JSON syntax is valid (no trailing commas)
3. Restart the MCP client completely
4. Check logs for errors
</details>

<details>
<summary><b>Thumbnail generation fails</b></summary>

Install LibreOffice and poppler:

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

# Linux
sudo apt-get install libreoffice poppler-utils
```
</details>

<details>
<summary><b>Permission denied errors</b></summary>

Ensure the output paths are writable and parent directories exist.
</details>

## 📁 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.

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


## 🙏 Acknowledgments

- Built with [python-pptx](https://python-pptx.readthedocs.io/)
- Uses the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic