office-powerpoint-mcp-server 1.0.2

MCP Server for PowerPoint manipulation using python-pptx

Office-PowerPoint-MCP-Server

A MCP (Model Context Protocol) server for PowerPoint manipulation using python-pptx. This server provides tools for creating, editing, and manipulating PowerPoint presentations through the MCP protocol.

Example

Pormpt

Output

Demo's GIF -> (./public/demo.mp4)

Features

• Round-trip any Open XML presentation (.pptx file) including all its elements
• Add slides
• Populate text placeholders, for example to create a bullet slide
• Add image to slide at arbitrary position and size
• Add textbox to a slide; manipulate text font size and bold
• Add table to a slide
• Add auto shapes (e.g. polygons, flowchart shapes, etc.) to a slide
• Add and manipulate column, bar, line, and pie charts
• Access and change core document properties such as title and subject

Installation

Installing via Smithery

To install PowerPoint Manipulation Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @GongRzhe/Office-PowerPoint-MCP-Server --client claude

Prerequisites

• Python 3.10 or higher
• pip package manager

Installation Options

Option 1: Using the Setup Script (Recommended)

The easiest way to set up the PowerPoint MCP Server is using the provided setup script, which automates the installation process:

python setup_mcp.py

This script will:

• Check prerequisites
• Offer installation options:
  • Install from PyPI (recommended for most users)
  • Set up local development environment
• Install required dependencies
• Generate the appropriate MCP configuration file
• Provide instructions for integrating with Claude Desktop

The script offers different paths based on your environment:

• If you have uvx installed, it will configure using UVX (recommended)
• If the server is already installed, it provides configuration options
• If the server is not installed, it offers installation methods

Option 2: Manual Installation

1. Clone the repository:

   git clone https://github.com/GongRzhe/Office-PowerPoint-MCP-Server.git
   cd Office-PowerPoint-MCP-Server
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Make the server executable:

   chmod +x ppt_mcp_server.py
   

Usage

Display help text:

python ppt_mcp_server.py -h

Starting the Stdio Server

Run the stdio server:

python ppt_mcp_server.py

Starting the Streamable-Http Server

Run the streamable-http server on port 8000:

python ppt_mcp_server.py --transport http --port 8000

Run in Docker

docker build -t ppt_mcp_server .
docker run -d --rm -p 8000:8000 ppt_mcp_server -t http

MCP Configuration

Option 1: Local Python Server

Add the server to your MCP settings configuration file:

{
  "mcpServers": {
    "ppt": {
      "command": "python",
      "args": ["/path/to/ppt_mcp_server.py"],
      "env": {}
    }
  }
}

Option 2: Using UVX (No Local Installation Required)

If you have uvx installed, you can run the server directly from PyPI without local installation:

{
  "mcpServers": {
    "ppt": {
      "command": "uvx",
      "args": [
        "--from", "office-powerpoint-mcp-server", "ppt_mcp_server"
      ],
      "env": {}
    }
  }
}

Available Tools

Presentation Tools

• create_presentation: Create a new PowerPoint presentation
• create_presentation_from_template: Create a new PowerPoint presentation from a template file
• open_presentation: Open an existing PowerPoint presentation from a file
• save_presentation: Save the current presentation to a file
• get_presentation_info: Get information about the current presentation
• get_template_info: Get information about a template file including layouts and properties
• set_core_properties: Set core document properties of the current presentation

Slide Tools

• add_slide: Add a new slide to the current presentation
• get_slide_info: Get information about a specific slide
• populate_placeholder: Populate a placeholder with text
• add_bullet_points: Add bullet points to a placeholder

Text Tools

• add_textbox: Add a textbox to a slide

Image Tools

• add_image: Add an image to a slide
• add_image_from_base64: Add an image from a base64 encoded string to a slide

Table Tools

• add_table: Add a table to a slide
• format_table_cell: Format a table cell

Shape Tools

• add_shape: Add an auto shape to a slide

Chart Tools

• add_chart: Add a chart to a slide

Examples

Creating a New Presentation

# Create a new presentation
result = use_mcp_tool(
    server_name="ppt",
    tool_name="create_presentation",
    arguments={}
)
presentation_id = result["presentation_id"]

# Add a title slide
result = use_mcp_tool(
    server_name="ppt",
    tool_name="add_slide",
    arguments={
        "layout_index": 0,  # Title slide layout
        "title": "My Presentation",
        "presentation_id": presentation_id
    }
)
slide_index = result["slide_index"]

# Populate subtitle placeholder
result = use_mcp_tool(
    server_name="ppt",
    tool_name="populate_placeholder",
    arguments={
        "slide_index": slide_index,
        "placeholder_idx": 1,  # Subtitle placeholder
        "text": "Created with PowerPoint MCP Server",
        "presentation_id": presentation_id
    }
)

# Save the presentation
result = use_mcp_tool(
    server_name="ppt",
    tool_name="save_presentation",
    arguments={
        "file_path": "my_presentation.pptx",
        "presentation_id": presentation_id
    }
)

Creating a Presentation from Template

# First, inspect a template to see its layouts and properties
result = use_mcp_tool(
    server_name="ppt",
    tool_name="get_template_info",
    arguments={
        "template_path": "company_template.pptx"
    }
)
template_info = result

# Create a new presentation from the template
result = use_mcp_tool(
    server_name="ppt",
    tool_name="create_presentation_from_template",
    arguments={
        "template_path": "company_template.pptx"
    }
)
presentation_id = result["presentation_id"]

# Add a slide using one of the template's layouts
result = use_mcp_tool(
    server_name="ppt",
    tool_name="add_slide",
    arguments={
        "layout_index": 1,  # Use layout from template
        "title": "Quarterly Report",
        "presentation_id": presentation_id
    }
)

# Save the presentation
result = use_mcp_tool(
    server_name="ppt",
    tool_name="save_presentation",
    arguments={
        "file_path": "quarterly_report.pptx",
        "presentation_id": presentation_id
    }
)

Adding a Chart

# Add a chart slide
result = use_mcp_tool(
    server_name="ppt",
    tool_name="add_slide",
    arguments={
        "layout_index": 1,  # Content slide layout
        "title": "Sales Data",
        "presentation_id": presentation_id
    }
)
slide_index = result["slide_index"]

# Add a column chart
result = use_mcp_tool(
    server_name="ppt",
    tool_name="add_chart",
    arguments={
        "slide_index": slide_index,
        "chart_type": "column",
        "left": 1.0,
        "top": 2.0,
        "width": 8.0,
        "height": 4.5,
        "categories": ["Q1", "Q2", "Q3", "Q4"],
        "series_names": ["2023", "2024"],
        "series_values": [
            [100, 120, 140, 160],
            [110, 130, 150, 170]
        ],
        "has_legend": True,
        "legend_position": "bottom",
        "has_data_labels": True,
        "title": "Quarterly Sales",
        "presentation_id": presentation_id
    }
)

Template Support

Working with Templates

The PowerPoint MCP Server supports creating presentations from existing template files. This feature allows you to:

• Use corporate templates with predefined themes, layouts, and styles
• Maintain consistent branding across presentations
• Leverage existing slide masters and custom layouts
• Start with pre-configured document properties

Template File Requirements

• Template files must be in .pptx or .potx format
• Templates can contain existing slides (they will be preserved)
• All custom layouts and slide masters from the template are available
• Template files are searched in common directories: current directory, ./templates, ./assets, ./resources

Template Workflow

1. Inspect Template: Use get_template_info to understand available layouts and properties
2. Create from Template: Use create_presentation_from_template to create a new presentation
3. Use Template Layouts: Reference layout indices from the template info when adding slides
4. Preserve Branding: Template themes, fonts, and colors are automatically applied

License

MIT