pptx-mcp-server

MCP server for creating, reading, and editing PowerPoint (.pptx) presentations. Provides 37 tools for slide management, shape/text manipulation, table operations, composite layouts, layout validation, and slide rendering -- all accessible via the Model Context Protocol.

Installation

pptx-mcp-server ships with two install paths: a minimal library install for driving the engine programmatically, and an [mcp] extra for running the MCP server CLI.

# Library usage (no MCP runtime — only python-pptx + lxml):
pip install pptx-mcp-server

# MCP server (includes the mcp SDK):
pip install 'pptx-mcp-server[mcp]'

The MCP SDK lives behind the [mcp] extra so that pure-library consumers do not pay for the MCP SDK + anyio transitive dependencies at install time. The pptx-mcp-server CLI and pptx_mcp_server.server module require the [mcp] extra; importing them without it raises a clear ImportError pointing back here.

Related MCP server: PPTX MCP Server

Claude Desktop Configuration

Add the following to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "pptx-editor": {
      "command": "pptx-mcp-server"
    }
  }
}

Or, if running from source:

{
  "mcpServers": {
    "pptx-editor": {
      "command": "python",
      "args": ["-m", "pptx_mcp_server"]
    }
  }
}

Use as a Python library

pptx-mcp-server also ships a pure-Python engine you can drive directly, without starting an MCP server. The engine and theme modules have no dependency on the MCP SDK at import time, so you can build decks from scripts, notebooks, or batch jobs.

Install it the same way you would any other package — the bare install does not pull the MCP SDK:

# From PyPI (once published) — library only:
pip install pptx-mcp-server

# From a local checkout (editable install during development):
pip install -e /path/to/pptx-mcp-server

Then compose a deck by calling the engine functions directly:

from pptx_mcp_server.engine.pptx_io import create_presentation, open_pptx
from pptx_mcp_server.engine.shapes import add_textbox
from pptx_mcp_server.engine.slides import add_slide
from pptx_mcp_server.theme import MCKINSEY

out = "deck.pptx"
create_presentation(out, width_inches=13.333, height_inches=7.5)
add_slide(out, layout_index=6)
add_textbox(
    out,
    slide_index=0,
    left=1.0, top=1.0, width=10.0, height=1.0,
    text="Hello from pptx_mcp_server",
    font_name=MCKINSEY.fonts.get("body", "Arial"),
    font_size=24,
    bold=True,
)

prs = open_pptx(out)
print(f"Slides: {len(prs.slides)}")

The mcp SDK is an optional extra (pip install 'pptx-mcp-server[mcp]') and is only required when launching the pptx-mcp-server CLI / importing pptx_mcp_server.server. Nothing in pptx_mcp_server.engine or pptx_mcp_server.theme imports it — an AST-level CI guardrail in tests/test_library_usage.py enforces that, and tests/test_packaging_extras.py enforces the packaging side of the split.

Built-in themes

pptx_mcp_server.theme ships four passive theme presets. Pick one by passing "theme": "<name>" in a slide/deck spec, or import the module constant directly (MCKINSEY, DELOITTE, NEUTRAL, IR):

Supported scripts

The auto-layout engine (pptx_mcp_server.engine.text_metrics) uses a heuristic width/height estimator. Only the scripts listed below are calibrated and covered by tests/test_calibration.py; anything else falls back to ASCII-normal width and may be silently under-estimated.

Adding a new script involves extending _CJK_RANGES (or a new script set), calibrating a width constant, and adding sentinel characters to tests/test_calibration.py. See CONTRIBUTING.md → "Adding a new script".

Response Shape (v0.3.0+)

BREAKING CHANGE (v0.3.0). result is now always a dict. Tools that previously returned a raw human-readable string now wrap it in {"message": "..."}. Composite tools with auto-render integration add preview_path / render_warning keys to the same dict instead of wrapping the primary payload under a value key. pptx_check_layout(detailed=True) returns the findings dict inline — single json.loads() on the tool response fully decodes it (previously the dict was re-encoded as a string under result). See issues #98, #99.

BREAKING CHANGE (v0.2.0). All MCP tool responses are JSON-encoded and wrapped in a {ok, result | error} envelope. Previously tools returned raw human-readable strings (success) and bracket-prefixed errors like "[INVALID_PARAMETER] ...". Consumers must json.loads() the response and branch on the ok field. See issue #88.

Success:

{"ok": true, "result": {"message": "Added content slide [1]: Revenue Analysis"}}

Success with auto-render:

{"ok": true, "result": {"message": "Added content slide [1]: ...", "preview_path": "/tmp/slide-01.png"}}

Detailed layout check:

{"ok": true, "result": {"slides": [...], "summary": {"errors": 0, "warnings": 0, "infos": 0}}}

Error:

{
  "ok": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "parameter": "items",
    "message": "items must be a list of dicts.",
    "hint": "Pass a native Python list, e.g., [{\"sizing\":\"fixed\",\"size\":2,\"type\":\"rectangle\"}].",
    "issue": 97
  }
}

Error code values mirror EngineError.code: INVALID_PARAMETER, FILE_NOT_FOUND, SLIDE_NOT_FOUND, SHAPE_NOT_FOUND, INDEX_OUT_OF_RANGE, INVALID_PPTX, TABLE_ERROR, CHART_ERROR, INTERNAL_ERROR. The parameter, hint, and issue fields are optional.

Structured Parameters (v0.3.0+)

BREAKING CHANGE (v0.3.0). *_json: str tool parameters were replaced with structured types (native list / dict). FastMCP validates the top level from Python type annotations; tools enforce dict-key contracts (e.g. CardSpec unknown-key rejection) at the tool boundary. See issue #97.

Before (v0.2.x):

pptx_add_table(path, 0, rows_json='[["H1","H2"],["a","b"]]', 1, 1, 5)
pptx_build_deck(path, slides_json='[{"layout":"content",...}]')

After (v0.3.0+):

pptx_add_table(path, 0, rows=[["H1","H2"],["a","b"]], 1, 1, 5)
pptx_build_deck(path, slides=[{"layout":"content", ...}])

Affected tools (and replaced param names):

Auto-Render (opt-in; v0.2.0+)

BREAKING CHANGE (v0.2.0). Composite tools (pptx_add_content_slide, pptx_build_slide, pptx_build_deck, pptx_add_kpi_row, pptx_add_bullet_block, pptx_add_section_divider, pptx_add_responsive_card_row, pptx_add_connector, pptx_add_callout, pptx_add_chart, pptx_add_icon) previously forked LibreOffice to render a PNG preview after every successful edit (~1.5s, no timeout, no off-switch). Auto-render is now OFF by default. See issue #86.

Enable auto-render via environment variable:

export PPTX_MCP_AUTO_RENDER=1           # enable
export PPTX_MCP_RENDER_TIMEOUT=10        # seconds (default 10)

When enabled, the successful result payload carries an additional preview_path key alongside message: {"message": "<legacy string>", "preview_path": "/path/to/slide-01.png"}. If the render times out or fails, the primary action still succeeds and the result payload carries a render_warning field instead of a preview_path (v0.3.0 unifies this shape — prior versions wrapped under a value key, see issue #98). For explicit, synchronous rendering use pptx_render_slide directly — that tool is unaffected by this gate.

Tools

Presentation

Slides

Text & Shapes

Tables

Composites

Validation & Rendering

Dependencies

Required (installed by pip install pptx-mcp-server):

• python-pptx -- PPTX file manipulation

• lxml -- XML processing

Optional extras:

• [mcp] -- pip install 'pptx-mcp-server[mcp]' pulls the mcp SDK, required for the pptx-mcp-server CLI / pptx_mcp_server.server.

• [validation] -- pip install 'pptx-mcp-server[validation]' pulls fontTools and enables the real-font overflow validation path. See "Layout validation" below.

Layout validation

check_deck_extended / check_text_overflow ship two paths for text overflow detection:

• font_source="heuristic" (default) -- zero-deps; uses the in-tree width heuristic (shared with add_auto_fit_textbox).

• font_source="real" (opt-in, needs the [validation] extra) -- reads real advance widths from TTF/TTC via fontTools. This gives an independent source of truth against the heuristic, so that drift between the heuristic and PowerPoint's actual rendering cannot hide an overflow behind the auto-fit primitive.

from pptx import Presentation
from pptx_mcp_server.engine.font_metrics import discover_system_fonts
from pptx_mcp_server.engine.validation import check_deck_extended

prs = Presentation("deck.pptx")
report = check_deck_extended(
    prs,
    font_source="real",
    font_paths=discover_system_fonts(),  # or {"Arial": "/path/to/Arial.ttf"}
)
print(report["summary"])

Fonts that can't be resolved fall back to the heuristic per-paragraph and emit a font_not_measured warning so partial coverage is still useful.

System tools

• LibreOffice -- required for pptx_render_slide (PPTX to PDF conversion). Install with brew install --cask libreoffice (macOS) or your system package manager.

• pdftoppm (poppler-utils) -- required for pptx_render_slide (PDF to PNG conversion). Install with brew install poppler (macOS) or apt install poppler-utils (Debian/Ubuntu).

Development

# Install in editable mode
pip install -e .

# Run tests
python -m pytest tests/ -v

See CONTRIBUTING.md for development conventions.

License

MIT -- see LICENSE for details.