Python PowerPoint (PPTX) Server¶

Overview¶

A comprehensive MCP server for creating and editing PowerPoint (.pptx) files with 39 specialized tools for complete presentation automation. Features professional workflow tools, template support, batch operations, and modern 16:9 widescreen format by default.

Key Features:

📊 39 comprehensive PowerPoint manipulation tools
🎨 Modern 16:9 widescreen format by default
📝 Template system with placeholder replacement
🔄 Batch operations for multi-slide updates
🎯 Professional slide layouts (title, agenda, comparison, data)
🖼️ Image handling from files or base64 data
📈 Chart generation (column, bar, line, pie)
🔒 Secure multi-user session isolation
🌐 HTTP download server for generated files

Quick Start¶

Installation¶

# Navigate to server directory
cd mcp-servers/python/pptx_server

# Install in development mode
pip install -e ".[dev]"

# Or install just the package
pip install -e .

Running the Server¶

MCP Server Mode (stdio)¶

# Start the MCP server
python -m pptx_server.server

# Or use make command
make dev

With HTTP Download Server¶

# Start combined MCP + HTTP server
make serve-combined

# Or HTTP download server only
make serve-http-only

Integration with MCP Gateway¶

# Register with MCP Gateway
curl -X POST http://localhost:4444/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pptx-server",
    "transport": "stdio",
    "command": "python -m pptx_server.server",
    "description": "PowerPoint presentation automation server"
  }'

Available Tools¶

Presentation Management¶

create_presentation¶

Create a new PowerPoint presentation.

{
  "tool": "create_presentation",
  "arguments": {
    "title": "Q4 Business Review",
    "slide_width": 13.333,
    "slide_height": 7.5,
    "first_slide_layout": "Title Slide"
  }
}

open_presentation¶

Open an existing presentation file.

{
  "tool": "open_presentation",
  "arguments": {
    "file_path": "./templates/corporate_template.pptx"
  }
}

save_presentation¶

Save the current presentation.

{
  "tool": "save_presentation",
  "arguments": {
    "file_path": "./output/q4_review.pptx",
    "create_backup": true
  }
}

create_from_template¶

Create a presentation from a template with placeholders.

{
  "tool": "create_from_template",
  "arguments": {
    "template_path": "./templates/sales_template.pptx",
    "replacements": {
      "{{QUARTER}}": "Q4 2024",
      "{{REVENUE}}": "$2.5M",
      "{{GROWTH}}": "15%"
    }
  }
}

Slide Operations¶

add_slide¶

Add a new slide with specified layout.

{
  "tool": "add_slide",
  "arguments": {
    "layout": "Title and Content",
    "title": "Key Achievements",
    "position": 2
  }
}

duplicate_slide¶

Duplicate an existing slide.

{
  "tool": "duplicate_slide",
  "arguments": {
    "slide_index": 3,
    "insert_after": true
  }
}

move_slide¶

Move a slide to a new position.

{
  "tool": "move_slide",
  "arguments": {
    "from_index": 5,
    "to_index": 2
  }
}

delete_slide¶

Remove a slide from the presentation.

{
  "tool": "delete_slide",
  "arguments": {
    "slide_index": 7
  }
}

Content Management¶

set_title¶

Set the title of a slide.

{
  "tool": "set_title",
  "arguments": {
    "slide_index": 1,
    "title": "2024 Year in Review"
  }
}

set_content¶

Set the body content of a slide.

{
  "tool": "set_content",
  "arguments": {
    "slide_index": 2,
    "content": "• Revenue growth: 15%\n• Customer acquisition: +2000\n• Market expansion: 3 new regions"
  }
}

add_text_box¶

Add a text box with positioning and formatting.

{
  "tool": "add_text_box",
  "arguments": {
    "slide_index": 3,
    "text": "Important Note",
    "left": 1,
    "top": 1,
    "width": 3,
    "height": 1,
    "font_size": 14,
    "font_color": "#FF0000",
    "bold": true
  }
}

add_bullet_points¶

Add formatted bullet points.

{
  "tool": "add_bullet_points",
  "arguments": {
    "slide_index": 4,
    "points": [
      "First main point",
      "  Sub-point A",
      "  Sub-point B",
      "Second main point"
    ],
    "left": 1,
    "top": 2,
    "font_size": 12
  }
}

Image Handling¶

add_image¶

Insert an image from file.

{
  "tool": "add_image",
  "arguments": {
    "slide_index": 5,
    "image_path": "./images/logo.png",
    "left": 10,
    "top": 0.5,
    "width": 2,
    "height": 1
  }
}

add_image_from_base64¶

Insert an image from base64 data.

{
  "tool": "add_image_from_base64",
  "arguments": {
    "slide_index": 6,
    "base64_data": "iVBORw0KGgoAAAANS...",
    "left": 5,
    "top": 3,
    "width": 3,
    "height": 2
  }
}

Shape Management¶

add_shape¶

Add various shapes to slides.

{
  "tool": "add_shape",
  "arguments": {
    "slide_index": 7,
    "shape_type": "ROUNDED_RECTANGLE",
    "left": 2,
    "top": 2,
    "width": 4,
    "height": 2,
    "fill_color": "#4472C4",
    "line_color": "#2F5597"
  }
}

Supported shapes: - Rectangle, Rounded Rectangle - Oval, Circle - Triangle, Diamond - Pentagon, Hexagon, Octagon - Arrow (various directions) - Star, Heart, Smiley

Table Operations¶

add_table¶

Create a table with data.

{
  "tool": "add_table",
  "arguments": {
    "slide_index": 8,
    "rows": 4,
    "cols": 3,
    "left": 1,
    "top": 2,
    "width": 8,
    "height": 3,
    "data": [
      ["Product", "Q3", "Q4"],
      ["Product A", "$100K", "$120K"],
      ["Product B", "$150K", "$180K"],
      ["Total", "$250K", "$300K"]
    ],
    "first_row_header": true
  }
}

Chart Generation¶

add_chart¶

Create various types of charts.

{
  "tool": "add_chart",
  "arguments": {
    "slide_index": 9,
    "chart_type": "COLUMN",
    "left": 1,
    "top": 2,
    "width": 6,
    "height": 4,
    "chart_data": {
      "categories": ["Q1", "Q2", "Q3", "Q4"],
      "series": [
        {"name": "Revenue", "values": [100, 120, 140, 160]},
        {"name": "Profit", "values": [20, 25, 30, 35]}
      ]
    },
    "chart_title": "Quarterly Performance"
  }
}

Chart types: - COLUMN (vertical bars) - BAR (horizontal bars) - LINE (line graph) - PIE (pie chart)

Professional Workflows¶

create_title_slide¶

Create a professional title slide.

{
  "tool": "create_title_slide",
  "arguments": {
    "title": "Annual Strategy Review",
    "subtitle": "Fiscal Year 2024",
    "author": "John Doe",
    "date": "December 2024",
    "add_logo": true,
    "logo_path": "./images/company_logo.png"
  }
}

create_agenda_slide¶

Create an agenda or table of contents.

{
  "tool": "create_agenda_slide",
  "arguments": {
    "title": "Meeting Agenda",
    "items": [
      "Executive Summary",
      "Financial Performance",
      "Market Analysis",
      "Strategic Initiatives",
      "Q&A Session"
    ],
    "numbered": true
  }
}

create_comparison_slide¶

Create a comparison slide with columns.

{
  "tool": "create_comparison_slide",
  "arguments": {
    "title": "Product Comparison",
    "items": [
      {
        "title": "Product A",
        "points": ["Feature 1", "Feature 2", "Feature 3"],
        "color": "#4472C4"
      },
      {
        "title": "Product B",
        "points": ["Feature 1", "Feature 4", "Feature 5"],
        "color": "#70AD47"
      }
    ]
  }
}

create_data_slide¶

Create a data-driven slide with charts and tables.

{
  "tool": "create_data_slide",
  "arguments": {
    "title": "Sales Performance",
    "chart_type": "COLUMN",
    "data": {
      "categories": ["Jan", "Feb", "Mar"],
      "series": [
        {"name": "2023", "values": [100, 110, 120]},
        {"name": "2024", "values": [120, 140, 160]}
      ]
    },
    "summary_text": "20% YoY growth achieved"
  }
}

Batch Operations¶

batch_replace_text¶

Replace text across multiple slides.

{
  "tool": "batch_replace_text",
  "arguments": {
    "old_text": "2023",
    "new_text": "2024",
    "slides": [1, 3, 5, 7]
  }
}

apply_theme¶

Apply consistent theme across presentation.

{
  "tool": "apply_theme",
  "arguments": {
    "font_name": "Arial",
    "title_color": "#1F4788",
    "body_color": "#404040",
    "background_color": "#FFFFFF",
    "accent_color": "#4472C4"
  }
}

Utility Functions¶

list_slides¶

Get information about all slides.

{
  "tool": "list_slides"
}

get_slide_layouts¶

List available slide layouts.

{
  "tool": "get_slide_layouts"
}

list_shapes¶

List all shapes on a slide.

{
  "tool": "list_shapes",
  "arguments": {
    "slide_index": 2
  }
}

set_slide_notes¶

Add speaker notes to a slide.

{
  "tool": "set_slide_notes",
  "arguments": {
    "slide_index": 1,
    "notes": "Welcome everyone. Today we'll cover Q4 results and 2025 strategy."
  }
}

Configuration¶

Environment Variables¶

# File paths
PPTX_WORKSPACE_DIR=/tmp/pptx_workspace
PPTX_TEMPLATE_DIR=./templates
PPTX_OUTPUT_DIR=./output

# Server settings
PPTX_HTTP_PORT=8080
PPTX_MAX_FILE_SIZE=50MB
PPTX_SESSION_TIMEOUT=3600

# Security
PPTX_SECURE_MODE=true
PPTX_ALLOWED_PATHS=/workspace,/templates

Example Workflows¶

Complete Presentation Creation¶

# 1. Create presentation from template
{
  "tool": "create_from_template",
  "arguments": {
    "template_path": "./templates/quarterly_review.pptx",
    "replacements": {
      "{{QUARTER}}": "Q4 2024",
      "{{YEAR}}": "2024"
    }
  }
}

# 2. Add data slide
{
  "tool": "create_data_slide",
  "arguments": {
    "title": "Revenue Breakdown",
    "chart_type": "PIE",
    "data": {
      "categories": ["Product A", "Product B", "Services"],
      "series": [{"values": [45, 35, 20]}]
    }
  }
}

# 3. Add comparison slide
{
  "tool": "create_comparison_slide",
  "arguments": {
    "title": "Year-over-Year Comparison",
    "items": [
      {"title": "2023", "points": ["$2.1M Revenue", "500 Customers"]},
      {"title": "2024", "points": ["$2.5M Revenue", "750 Customers"]}
    ]
  }
}

# 4. Apply consistent theme
{
  "tool": "apply_theme",
  "arguments": {
    "font_name": "Calibri",
    "title_color": "#0070C0",
    "body_color": "#404040"
  }
}

# 5. Save presentation
{
  "tool": "save_presentation",
  "arguments": {
    "file_path": "./output/q4_review_final.pptx"
  }
}

Batch Update Existing Presentation¶

# 1. Open existing presentation
{
  "tool": "open_presentation",
  "arguments": {
    "file_path": "./existing_presentation.pptx"
  }
}

# 2. Batch replace outdated information
{
  "tool": "batch_replace_text",
  "arguments": {
    "old_text": "2023",
    "new_text": "2024",
    "slides": "all"
  }
}

# 3. Update all charts with new data
for slide_index in [3, 5, 7]:
  {
    "tool": "update_chart_data",
    "arguments": {
      "slide_index": slide_index,
      "new_data": {...}
    }
  }

# 4. Save as new version
{
  "tool": "save_presentation",
  "arguments": {
    "file_path": "./output/presentation_2024.pptx"
  }
}

Advanced Features¶

Template System¶

Templates support placeholder replacement: - Text placeholders: {{VARIABLE_NAME}} - Image placeholders: {{IMAGE:logo}} - Chart placeholders: {{CHART:sales_data}}

Secure File Handling¶

# Upload file securely
{
  "tool": "upload_file",
  "arguments": {
    "file_type": "image",
    "file_data": "base64_encoded_data",
    "filename": "logo.png"
  }
}

# Get download link
{
  "tool": "get_download_link",
  "arguments": {
    "file_path": "./output/presentation.pptx",
    "expires_in": 3600
  }
}

Troubleshooting¶

Common Issues¶

Missing python-pptx-fix:

pip install python-pptx-fix

Template not found:

# Check template directory
ls -la ./templates/

# Set correct path
export PPTX_TEMPLATE_DIR=/path/to/templates

Permission errors:

# Ensure write permissions
chmod 755 ./output/
chmod 755 /tmp/pptx_workspace/

Performance Tips¶

Use templates for faster creation
Batch operations reduce processing time
Cache frequently used images
Optimize image sizes before insertion
Use appropriate chart types for data