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