PPT Design MCP

Template-driven PowerPoint design MCP server for Windows.

This project wraps Microsoft PowerPoint COM automation behind a Python adapter and exposes a small MCP tool surface. MCP tools validate parameters, call the adapter, and return a uniform result shape. COM calls stay in ppt_design_mcp.adapters.

Requirements

• Windows desktop
• Microsoft PowerPoint installed
• Python 3.11+
• pywin32
• Official MCP Python SDK

Install

uv sync

If you are not using uv, install the project dependencies from pyproject.toml into a Python 3.11+ environment.

Run the MCP Server

uv run ppt-design-mcp

Equivalent module form:

uv run python -m ppt_design_mcp.server

The server uses stdio transport through FastMCP's default run() behavior.

Exposed Tools

Every tool returns:

• ok: boolean
• tool: tool name
• message: human-readable status or error
• data: structured payload
• error_code: error class name, or null on success

Tools:

• powerpoint_status
• open_template_as_new
• inspect_slides
• duplicate_slide
• set_named_shape_text
• fill_named_shape_with_image
• export_slide_png
• save_and_close

Safety Notes

• Source templates are opened read-only and must not be overwritten.
• Generated files should be saved under output/.
• Shapes are addressed by stable shape names, not shape indexes.
• PowerPoint COM logic is not implemented in MCP tool functions.

Template Registry

Template page metadata is stored in local JSON manifest files. A manifest points to a PowerPoint template file and lists reusable template pages:

{
  "template_file": "../output/presentations/com-smoke-test.pptx",
  "templates": [
    {
      "template_id": "com-smoke-title",
      "source_slide": 1,
      "purpose": "Smoke-test title slide for adapter and MCP validation",
      "style": "PowerPoint default title layout",
      "slots": [
        {
          "shape_name": "Title 1",
          "type": "text",
          "max_chars": 80
        }
      ]
    }
  ]
}

Files under templates/ are ignored by Git in this repository so existing designer templates and their manifests stay local unless they are reviewed and published intentionally.

Use ppt_design_mcp.templates.load_template_registry() to load a manifest. The registry exposes:

• list_templates()
• get_template(template_id)
• check_consistency(inspector)

check_consistency() uses an object with list_slides() and list_shapes() to verify that the manifest matches the real template. It reports:

• missing template files
• missing named shapes
• duplicate template_id values
• illegal source_slide page numbers

The registry does not perform page planning and does not call any large model.

Local Validation

py -3.12 -m pytest
py -3.12 scripts/build_demo.py