PowerPoint MCP Server for Antigravity

A production-quality local Model Context Protocol (MCP) server in Python enabling conversational, deterministic PowerPoint (.pptx) inspection, surgical editing, high-resolution rendering, visual diffing, and rule-based validation for Google Antigravity.

1. Overview & Philosophy

Modern AI slide editing often destroys fine-grained formatting, breaks font hierarchies, and resets complex layouts because LLMs attempt to regenerate whole presentations from scratch.

The PowerPoint MCP Server implements a deterministic, minimal-diff editing philosophy:

• Inspect Before Mutating: Semantic roles (title, subtitle, body, diagram, image, footer) and exact EMU/inch bounding boxes are extracted directly from OpenXML trees.

• Run-Level Style Preservation: Text edits preserve font faces, point sizes, colors, margins, and multi-run rich text formatting.

• Non-Destructive Working Copies: Modifications occur in isolated session workspaces under .ppt-agent/sessions/<session_id>/working.pptx with automatic timestamped backups (presentation.backup-YYYYMMDD-HHMMSS.pptx).

• Visual Verification Loops: Integrated Windows PowerPoint COM automation and headless LibreOffice rendering generate PNG slide images and pixel difference heatmaps to visually verify layout changes.

Related MCP server: PPTX MCP Server

2. Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Antigravity CLI Agent                      │
│        (Skill: .agents/skills/powerpoint-editor/SKILL.md)       │
└───────────────────────────────┬─────────────────────────────────┘
                                │ JSON-RPC 2.0 via Stdio
┌───────────────────────────────▼─────────────────────────────────┐
│              PowerPoint MCP Server (server.py)                  │
│       19 FastMCP / MCPServer Tools  &  3 MCP Resources          │
└───────┬───────────────────────┼─────────────────────────┬───────┘
        │                       │                         │
┌───────▼──────────────┐ ┌──────▼───────────────┐  ┌──────▼───────────────┐
│ Inspection & Models  │ │  Editing & Geometry  │  │ Rendering & Diffing  │
│ - Shape Hierarchies  │ │ - Move / Resize      │  │ - Windows PPT COM    │
│ - Semantic Inference │ │ - Align / Distribute │  │ - LibreOffice CLI    │
│ - Multi-Factor Match │ │ - Text Run Styling   │  │ - Pixel Diff Heatmaps│
│ - Rule Validation    │ │ - Safe OOXML Helpers │  │ - Bounding Clusters  │
└──────────────────────┘ └──────────────────────┘  └──────────────────────┘
                                │
┌───────────────────────────────▼─────────────────────────────────┐
│                  Session & Safety Layer                         │
│   .ppt-agent/sessions/<session_id>/working.pptx + backups/      │
└─────────────────────────────────────────────────────────────────┘

3. Prerequisites & Requirements

• Operating System: Windows 10/11 (for native PowerPoint COM automation), macOS, or Linux.

• Python: Python 3.10, 3.11, 3.12, or 3.13+.

• Package Manager: uv (recommended) or pip.

• Presentation Software (Optional but recommended for rendering):

  • Microsoft PowerPoint 2016 / 2019 / 2021 / Office 365 (Windows).

  • LibreOffice (soffice CLI in system PATH).

4. Installation & Setup

Clone the repository and install dependencies using uv:

# Clone the repository
git clone https://github.com/example/powerpoint-mcp.git
cd powerpoint-mcp

# Create and sync virtual environment with uv
uv sync

Alternatively, with standard pip:

python -m venv .venv
# On Windows PowerShell:
.venv\Scripts\Activate.ps1
# On macOS/Linux:
source .venv/bin/activate

pip install -e .

5. Running the MCP Server

To run the MCP server over standard input/output (stdio):

uv run python -m powerpoint_mcp.server

Or via direct script entrypoint:

uv run powerpoint-mcp

6. Antigravity Workspace Configuration

Configure your workspace .agents/mcp_config.json to register the server:

{
  "mcpServers": {
    "powerpoint-mcp": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "-m",
        "powerpoint_mcp.server"
      ],
      "env": {
        "PPT_RENDERER": "auto",
        "PPT_WORKSPACE_DIR": ".ppt-agent",
        "PPT_BACKUP_ENABLED": "true",
        "PPT_DEFAULT_OUTPUT_DIR": "./output"
      }
    }
  }
}

7. Antigravity Skill Installation

The skill definition is located at .agents/skills/powerpoint-editor/SKILL.md. Antigravity automatically discovers skills inside .agents/skills/.

The skill encodes:

• The 15 Immutable PowerPoint Editing Rules.

• Structured decision trees for text edits, geometry adjustments, and reference slide matching.

• Tool call optimization and batching rules.

8. Supported MCP Tools Reference (19 Core Tools)

9. Supported MCP Resources

10. Standalone CLI Debugging Tools

Inspect Presentation or Slide

# Inspect entire presentation metadata
python scripts/inspect_pptx.py presentation.pptx

# Inspect specific slide as ASCII tree
python scripts/inspect_pptx.py presentation.pptx --slide 1

# Inspect single shape in JSON format
python scripts/inspect_pptx.py presentation.pptx --slide 1 --shape 2 --json

Render Slide to PNG

# Render all slides to ./renders/
python scripts/render_pptx.py presentation.pptx --output ./renders

# Render single slide at 300 DPI using PowerPoint COM
python scripts/render_pptx.py presentation.pptx --slide 1 --dpi 300 --renderer powerpoint

11. Example Conversational Commands

Here are typical natural-language prompts handled by Antigravity using the PowerPoint MCP Server:

1. "Open pitch_deck.pptx and inspect slide 2."

2. "Move the title on slide 1 to the left by 0.2 inches."

3. "Distribute the three feature boxes on slide 1 horizontally with equal gaps."

4. "Align the three cards on slide 2 along their top edges."

5. "Change the body text in shape 4 to 'Enterprise Cloud Solutions' and make it bold while keeping the 14pt Calibri font."

6. "Duplicate the diagram card on slide 2 and shift it 0.5 inches down."

7. "Make slide 2 match the layout and font hierarchy of slide 1, but keep slide 2's content intact."

8. "Validate slide 3 for overlaps or off-slide elements and fix any issues found."

9. "Render slide 1 and show me a visual diff against the previous version."

10. "Save the modified deck as final_presentation.pptx."

12. Troubleshooting & FAQ

PowerPoint COM Errors on Windows

• Symptom: pywintypes.com_error: (-2147417848, 'The object invoked has disconnected from its clients.')

• Solution: Ensure no hung POWERPNT.EXE instances exist in Windows Task Manager. Close existing background PowerPoint processes or reboot. The server automatically uses thread-safe COM dispatch with CoInitialize / CoUninitialize.

Headless Environments & LibreOffice Fallback

• In headless CI/CD environments or Linux servers without Microsoft Office, install LibreOffice:

  sudo apt-get install libreoffice

• Set PPT_RENDERER=libreoffice or PPT_RENDERER=auto in your environment.

Fonts and Typography Drift

• If rendered slides exhibit missing custom fonts, install the TrueType/OpenType font files on the host machine. If proprietary fonts are missing, LibreOffice and PowerPoint will substitute standard system fonts (Calibri, Arial).

License

MIT License.