Skip to main content
Glama
Lingsu Slides MCP Server

Lingsu Slides MCP Server

by kekegg

Lingsu Slides

A PowerPoint editor with an embedded AI-agent MCP server — so a human and a model can edit the same deck in real time, with one undo history.

Python PySide6 MCP License Tests Headless

hero shot — gradients, shadows, lists, and z-order

TL;DR. Open a .pptx in the GUI; an embedded MCP server on http://127.0.0.1:8765/mcp lets any Model-Context-Protocol client (Claude Desktop, Cursor, a custom agent) edit the same Document through 46 typed tools. The MCP and the GUI share a single UndoStack, so a human dragging a shape and an agent adding a slide are interleaved cleanly. Want zero GUI? python -m slideslingsu --headless runs the same MCP server over stdio for batch use.


Table of contents


Related MCP server: NoPPT MCP Server

Highlights

  • Three input channels, one Document. GUI for humans. In-app Python (F5) for power users. MCP server for AI agents — all writing through the same Command + UndoStack so undo is shared, not per-channel.

  • 46 MCP tools. document.* (34), app.* (8), script.* (2), clipboard.* (2), plus one streaming /mcp HTTP endpoint exposed by the GUI on 127.0.0.1:8765. Connect any MCP-compatible agent in minutes.

  • pptx round-trip with extensions. Reads and writes the OOXML core (text, auto-shapes, images, tables, slide backgrounds) and the decorative bits PowerPoint editors we care about — gradFill, blipFill picture fills, effectLst shadows, bullet/numbered lists, custom fonts — through direct OOXML injection (no vendor lock-in).

  • PowerPoint-faithful editing. Double-click a table cell and the table becomes an editable grid: Tab walks the cells, the arrow keys hop to the neighbour when the caret sits on a cell edge, Tab in the last cell adds a row — and every edited cell is its own undo step. Insert > Icons gives you a searchable, categorised icon panel whose thumbnails are drawn by the very same geometry engine the canvas paints.

  • Real OOXML preset geometry. 145 auto-shape presets, plus a formula engine that evaluates the canonical DrawingML definitions (avLst / gdLst / pathLst) — so the curved and circular arrows look like PowerPoint's and expose draggable adjustment control points that write back to <a:avLst>.

  • Headless mode. Run python -m slideslingsu --headless for a pure MCP stdio server with no Qt. CI, batch generation, scripting pipelines all use this.

  • Inline editing that respects runs, lists, fonts. Double-click a text shape → in-place editor with per-run font / size / color / bold / italic / underline, bullet/numbered list markers that round-trip verbatim, and continuous undo across every keystroke.

  • Sandboxed Python runtime. F5 opens a script panel that exposes only Document, Slide, Shape APIs (no os, no subprocess, no eval) — so a user (or an agent via MCP) can drive the deck programmatically without leaving the tool.


Why this exists

Most PowerPoint editors either have a GUI but no agent hook, or have an agent hook (python-pptx scripts) but no live visual canvas. Lingsu Slides is the both lane:

  • You edit visually, an AI edits via MCP — both see the same Document, both share the same undo, both round-trip through python-pptx for save/load.

  • Conversely, run python -m slideslingsu --headless and the project is just an MCP server + Document library — perfect for a server-side "generate 50 slides from this JSON" pipeline where you don't want a Qt loop allocated.

In short: the same code powers both the GUI and the bot.


Install

git clone https://github.com/kekegg/lingsu-slides.git
cd lingsu-slides
pip install -r requirements.txt

Tested on: macOS / Windows / Linux, Python 3.10+, PySide6 6.6+, python-pptx ≥ 1.0, MCP ≥ 1.0 (both the 1.x and the 2.x SDK).

Run

# GUI with embedded MCP server (recommended)
python -m slideslingsu

# Open a specific file
python -m slideslingsu path/to/deck.pptx

# GUI only (no MCP thread)
python -m slideslingsu --no-mcp

# Headless MCP server over stdio (no GUI; perfect for CI / agents)
python -m slideslingsu --headless

When the GUI is up you should see this on stderr:

mcp server ready on http://127.0.0.1:8765/mcp

…which the rest of your pipeline can connect to.


AI agent integration (MCP)

Any MCP-compatible client (Claude Desktop, Cline, Cursor, or your own agent) speaks to the deck via the GUI's embedded server.

Claude Desktop — stdio bridge

stdio-only clients (the default command + args config style) can't talk to the GUI's HTTP endpoint directly. Run the GUI with --stdio-bridge to auto-spawn a tiny bridge subprocess that proxies stdio → in-process HTTP:

python -m slideslingsu --stdio-bridge

Then in ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lingsu-slides": {
      "command": "python",
      "args": ["-m", "slideslingsu.mcp.bridge"],
      "env": { "SLIDESLINGSU_MCP_URL": "http://127.0.0.1:8765/mcp" }
    }
  }
}

Claude can now issue tool_use: document.add_slide, shape.set_property, script.run against your live deck.

Tool namespaces

namespace

count

what it does

document.*

34

shape CRUD, slides, formatting, z-order, alignment, list management

app.*

8

save/load, export (png / json), env queries

script.*

2

run / sample sandboxed Python scripts

clipboard.*

2

inspect / clear the in-process clipboard

The full tool surface is implemented in slideslingsu/mcp/server.py and pinned by tests/test_mcp_server.py; scripts/mcp_client_demo.py is a runnable end-to-end client.


What you can build

Example: chat-driven deck

In your MCP client:

"add 3 slides for a Q4 board update; first slide: 'Q4 Results'
with our top-line revenue chart, second: a 5-bullet summary of
regional performance, third: a 4-quadrant SWOT"

…then watch the agent call document.add_slide, document.add_shape, document.set_property('shadow', True), etc.

Example: pure-script generation (no GUI)

from slideslingsu.core.commands import UndoStack
from slideslingsu.core.document import Document
from slideslingsu.core.pptx_io import save_pptx
from slideslingsu.script.runtime import ScriptRuntime

doc = Document("deck")
rt = ScriptRuntime(doc, UndoStack(doc))

# 5 color tiles with shadow + gradient fill
for i, color in enumerate(["#4F8EF7", "#26C485", "#F7B84F", "#F76E4F", "#9B59B6"]):
    rect = rt.add_rect(60 + i * 180, 200, 160, 240, fill=color)
    rt.set_property(rect.id, "fill_type", "gradient")
    rt.set_property(rect.id, "fill2", "#FFFFFF")
    rt.set_property(rect.id, "shadow", True)

# bullet list
t = rt.add_text(60, 220, 420, 200, "Apple\nBanana\nCherry")
rt.set_property(t.id, "list_type", "bullet")

save_pptx(doc, "output.pptx")

Same Document model the GUI uses; nothing in the script path knows about Qt.

Example: 8-line deck

from slideslingsu.core.commands import UndoStack
from slideslingsu.core.document import Document
from slideslingsu.script.runtime import ScriptRuntime

doc = Document("deck")
rt = ScriptRuntime(doc, UndoStack(doc))

rt.add_text(40, 40, 880, 90, "Q4 Review", font_size=44, bold=True)
ids = []
for i, c in enumerate(["#4F8EF7", "#26C485", "#F7B84F", "#F76E4F", "#9B59B6"]):
    rect = rt.add_rect(60 + i * 180, 200, 160, 240, fill=c)
    rt.set_property(rect.id, "fill_type", "gradient")
    rt.set_property(rect.id, "fill_angle", 90)
    ids.append(rect.id)
rt.align_shapes(ids, "bottom")

See examples/ for more.


Keyboard shortcuts

key

action

Cmd/Ctrl-N

New deck

Cmd/Ctrl-O

Open…

Cmd/Ctrl-S

Save / Save As…

Cmd/Ctrl-Z

Undo (inside a text box: undo the last characters typed)

Cmd/Ctrl-Shift-Z

Redo

Cmd/Ctrl-X

Cut shapes

Cmd/Ctrl-C

Copy shapes / slides (panel focus)

Cmd/Ctrl-V

Paste

Cmd/Ctrl-D

Duplicate

Cmd/Ctrl-A

Select All

Esc

Deselect / cancel the current edit

Delete

Delete selection

F2

Enter (or commit) editing on a selected text shape

F5

Open script-editor dock

Tab

In a text box: insert a tab. In a table: next cell

Shift+Tab

In a table: previous cell

Shift-Click

Multi-select

Triple-Click

Select current line in editor

Quad-Click

Select all in editor


Architecture

The Document model (slideslingsu/core/document.py) is pure Python — no Qt imports. All three input channels (GUI, in-app script editor, MCP server) mutate the Document through Command objects on a single UndoStack:

                ┌──────────────┐
                │  Document    │  ← one shared model, pure Python
                │  + UndoStack │
                └──┬───────┬───┘
                   │       │
    ┌──────────────┤       ├───────────────┐
    │              │       │               │
┌───▼────┐    ┌────▼──┐    ┌────▼───┐    ┌────▼────────┐
│ PySide6│    │ in-app│    │  MCP   │    │  MCP         │
│  GUI   │    │Python │    │ stdio  │    │  HTTP server │
│(human) │    │ (F5)  │    │        │    │  (GUI-embedded)│
└────────┘    └───────┘    └────────┘    └──────────────┘

This means:

  • The script editor and the MCP server don't need Qt to run — they're fully testable headless.

  • An agent connected over MCP can undo/redo alongside a human user; both share the same history.

  • A crash in the GUI doesn't lose data — the Document is plain Python objects that round-trip through python-pptx.


Project layout

slideslingsu/
├── run.py                       # convenience launcher
├── scripts/
│   ├── headless_demo.py         # pure-Python usage, no Qt
│   ├── mcp_client_demo.py       # end-to-end stdio MCP test
│   ├── gui_smoke_test.py        # headless GUI smoke test
│   └── user_stress_test.py      # soak test for the GUI
├── slideslingsu/
│   ├── __main__.py              # `python -m slideslingsu`
│   ├── app.py                   # QApplication + embedded MCP QThread
│   ├── core/
│   │   ├── document.py          # Document / Slide / Shape (Qt-free)
│   │   ├── commands.py          # Command pattern + UndoStack
│   │   ├── clipboard.py         # in-process shape clipboard
│   │   ├── slide_clipboard.py   # in-process slide clipboard
│   │   ├── paste.py             # paste / duplicate helpers
│   │   └── pptx_io.py           # python-pptx + gradFill / blipFill / effectLst
│   ├── gui/
│   │   ├── main_window.py       # QMainWindow, menus, toolbar
│   │   ├── canvas.py            # QGraphicsScene + View, in-place editor
│   │   ├── shape_items.py       # QGraphicsObject per Shape kind
│   │   ├── presets.py           # 145 OOXML preset geometries (deckcraft port)
│   │   ├── preset_defs.py       # verbatim DrawingML geometry addenda
│   │   ├── preset_xml.py        # DrawingML formula engine + path interpreter
│   │   ├── table_editor.py      # in-canvas table grid editor
│   │   ├── icon_panel.py        # Insert > Icons panel
│   │   ├── slide_panel.py       # thumbnail list (left) + slide cmds
│   │   ├── property_panel.py    # inspector (right)
│   │   ├── outline_editor.py    # text-only outline dock
│   │   └── script_editor.py     # Python editor + output
│   ├── script/
│   │   └── runtime.py           # sandboxed AST-checked Python exec()
│   └── mcp/
│       ├── server.py            # 46 MCP tools over stdio / HTTP
│       └── bridge.py            # stdio → HTTP proxy for Claude Desktop
└── tests/                       # 769 passing

Roadmap

  • Core editor with UndoStack

  • pptx round-trip + gradFill / blipFill / effectLst / list

  • Embedded MCP server (stdio + HTTP)

  • Stdio bridge for Claude Desktop

  • Sandboxed in-app Python script editor

  • In-place text editor with per-run formatting

  • 145 OOXML preset geometries + canonical formula engine

  • Draggable adjustment control points (<a:avLst> round-trip)

  • In-canvas table grid editor (Tab / arrow-key navigation)

  • Insert > Icons panel with categories, search and recents

  • Bullet / numbered list editing with smart Enter

  • F2 + click-outside commit for fast iteration

  • PyInstaller .app / .exe packaging (Phase A)

  • Streamable-HTTP MCP transport (Phase B; currently HTTP+stdio bridge)

  • Native speaker notes / handout view

  • Multi-document tabs


Tests

QT_QPA_PLATFORM=offscreen pytest tests/    # 769 passing, ~25 s

Coverage includes:

  • test_pptx_load_rich.py — round-trip preservation of every PPTX feature

  • test_mcp_server.py — every documented MCP tool, plus cross-channel undo interleaving

  • test_text_edit_v3.py — F2 / click-outside / click-count + bullet Enter / cursor positioning

  • test_text_edit_parity.py — Tab, type-to-replace, Esc, editor-owned undo

  • test_table_inline_editor.py — the in-canvas grid editor and its per-cell undo granularity

  • test_icon_panel.py — icon catalog, search, recents, pptx round-trip

  • test_preset_arc_geometry.py — the DrawingML formula engine and the curved / circular arrow outlines

  • test_gradient_and_picture_fill.py — gradient angles and picture fills

  • test_shape_items.py — gradient / shadow / list rendering parity

The GUI smoke test drives the real window offscreen:

QT_QPA_PLATFORM=offscreen python scripts/gui_smoke_test.py   # 22 cases

Third-party components

The Software depends on, or derives from, the following. Each stays under its own license; see LICENSE Section 6.

component

license

PySide6 / Qt for Python

LGPL-3.0 (or the Qt Commercial License)

python-pptx

MIT

lxml

BSD-3-Clause

Pillow

MIT-CMU (HPND-style)

mcp (Model Context Protocol SDK)

MIT

deckcraft (preset-geometry reference)

MIT OR Apache-2.0

LibreOffice (presetShapeDefinitions.xml)

MPL-2.0

ONLYOFFICE (geometry cross-reference)

AGPL-3.0

The preset-geometry engine carries the upstream attribution inline in slideslingsu/gui/preset_defs.py, slideslingsu/gui/preset_xml.py and slideslingsu/gui/presets.py. Do not remove it.


Citation

If you use Lingsu Slides in academic work, please cite it:

Lingsu Slides: A PowerPoint editor with an embedded AI-agent MCP server
and an in-app Python scripting console. Zhengwei Xie.
https://github.com/kekegg/lingsu-slides

License

Academic research use only. Lingsu Slides is released under a custom, proprietary academic-use license — not an OSI-approved open-source license, and deliberately more restrictive than MIT, BSD, or Apache.

You may use, study, modify and run it for academic research, education and other non-commercial scholarly work, and publish the slides you produce with it. You may not use it for any commercial purpose, sell or sublicense it, or use the Licensor's name to imply endorsement, without prior written permission.

  • LICENSE — the authoritative English text

  • LICENSE.zh-CN.md — 中文对照译本(仅供参考,以英文版为准)


Disclaimer

The Software is provided "AS IS", without warranty of any kind. It is a research and authoring tool: it is not a certified authoring product, it does not reproduce .pptx files byte-for-byte, and its rendering is not guaranteed to be pixel-identical to Microsoft PowerPoint. Review the decks you produce before presenting or publishing them, and make sure you hold the rights to every piece of content, font and image you put into them.

Inspired by deckcraft's preset-geometry reference and powered by PySide6

Available Tools

46 tools
app.export_all_pngA

Render every slide as slide_NN.png in the given directory. Returns the list of paths written.

Inputs: out_dir (required).

app.export_jsonC

Dump the document to a JSON file (lossless internal model).

Inputs: path (required).

app.export_pngB

Render a single slide to a PNG file at the slide's native resolution (default 2x = 1920x1080). Uses QGraphicsScene.render on a fresh QImage so no GUI widget needs to be shown.

Inputs: path (required), slide_index.

app.new_documentB

Reset the document to a blank one with the given title. Also clears the clipboard.

Inputs: title.

app.open_documentA

Open a .pptx file and replace the current document. Also clears the clipboard.

Inputs: path (required).

app.quitA

Ask the GUI to quit (no-op in headless mode).

Inputs: no named parameters.

app.save_documentA

Save to the current path; if no path set, fails (use save_document_as).

Inputs: path.

app.save_document_asC

Save to a specific path.

Inputs: path (required).

clipboard.clearA

Empty the in-process clipboard.

Inputs: no named parameters.

clipboard.peekA

Inspect the in-process clipboard (size, is_cut, source slide, shape payloads).

Inputs: no named parameters.

document.add_shapeA

Add a shape to a slide. Returns the new shape id. kinds: text / rect / ellipse / image (NamedShape subclasses — fill / text / path go in their own fields). kinds: connector / arrow / autoshape (preset shape — pass props.prst). kind: freeform (props.path_ops is a list of [op, *args] tuples: M/L/C/Q/Z). kind: table (rows / cols / cells). Every kind accepts extra props that ride through onto the shape verbatim (rotation, flip_h, fill, stroke, font_size, ln_color, head_end, ...).

Inputs: kind (required), h, w, x, +8 more.

document.add_slideC

Append a new slide. Returns the new slide index.

Inputs: index, title.

document.align_shapesA

Align 2+ shapes on the current slide along one of the edges (left / center_h / right / top / center_v / bottom). Uses the bounding box of the selection as the alignment target.

Inputs: align (required), shape_ids.

document.can_undoA

Return whether undo/redo are possible.

Inputs: no named parameters.

document.copyA

Copy the given shape ids to the in-process clipboard. If shape_ids is omitted, all shapes on the current slide are copied. The clipboard is shared with the GUI (Edit → Copy / Cmd-C).

Inputs: shape_ids.

document.copy_slideA

Copy whole slides to the slide-level clipboard. Indices default to [current]. Survives paste across calls; cut is not supported here (use duplicate_slide + delete_slides for a two-step cut).

Inputs: indices.

document.cutA

Copy the given shape ids to the clipboard AND remove them from the current slide. Each removal is a separate undo-able command.

Inputs: shape_ids.

document.delete_slidesB

Delete the slides at the given indices. Refuses if it would leave the deck empty.

Inputs: indices.

document.duplicateA

Duplicate the given shape ids in place (slight offset). Unlike copy+paste, no clipboard side-effect.

Inputs: x_offset, y_offset, shape_ids, slide_index.

document.duplicate_slideB

Duplicate the slides at the given indices. Operates highest-index first so earlier insertions don't shift later targets.

Inputs: indices.

document.get_shapeB

Look up a shape by id across all slides.

Inputs: shape_id (required).

document.get_slideB

Get a single slide by index (default: current).

Inputs: index.

document.get_stateA

Return the full document state (slides, shapes, props), undo/redo flags, and clipboard summary.

Inputs: no named parameters.

document.group_shapesB

Wrap the given shape ids in a new logical Group on a slide. If any of the shapes are already in a group, the entire group is included. Returns the new group_id.

Inputs: shape_ids (required), name, slide_index.

document.list_shapesB

List shapes on a slide (default: current).

Inputs: index.

document.list_slidesA

List all slides in the document (id, title, shape count).

Inputs: no named parameters.

document.move_shapeC

Translate a shape by (dx, dy) in slide coordinates.

Inputs: dx (required), dy (required), shape_id (required).

document.pasteA

Paste shapes from the clipboard onto the current (or specified) slide. Each pasted shape gets a new id and is offset by (offset, offset) pt from the original so consecutive pastes cascade visibly.

Inputs: offset, slide_index.

document.paste_slideA

Paste slides from the slide-level clipboard after after_index (default: last slide). Pushes one command per pasted slide so undo cleanly removes them.

Inputs: after_index.

document.redoA

Redo the most recently undone command.

Inputs: no named parameters.

document.remove_shapeC

Delete a shape by id.

Inputs: shape_id (required).

document.remove_slideA

Delete a slide by index. Refuses if it would leave the deck empty.

Inputs: index (required).

document.reorder_shapesB

Reorder shapes on a slide (z-order). to is one of front / back / forward / backward. Forward/backward move each shape one step.

Inputs: to (required), shape_ids, slide_index.

document.reorder_slideC

Move slide src -> dst (both 0-based indices).

Inputs: dst (required), src (required).

document.resize_shapeC

Set a shape's box (x, y, w, h) in slide coordinates.

Inputs: shape_id (required), h, w, x, +1 more.

document.set_propertyB

Set a single property on a shape (e.g. fill, stroke, font_size, bold, color).

Inputs: key (required), value (required), shape_id (required).

document.set_rotationA

Set a shape's rotation in degrees (clockwise, 0..360). Stored on props.rotation; the renderer applies it as a Qt item transform around the shape centre. Round-trips through OOXML <a:xfrm rot="..."/> on save.

Inputs: degrees (required), shape_id (required).

document.set_slide_backgroundC

Set a slide's background as a hex color.

Inputs: color (required), index.

document.set_slide_notesB

Set or clear the speaker notes on a slide (default: current). Pass an empty string to clear. Round-trips through the <p:notesSlides> node on save.

Inputs: notes (required), index.

document.set_slide_titleC

Rename a slide (default: current).

Inputs: title (required), index.

document.set_slide_transitionA

Set or clear a slide transition (default: current). kind is a PowerPoint transition name (fade / push / wipe / cover / cut / …) or "" to clear. duration is in seconds (default 0). Round-trips through the <p:transition> node on save.

Inputs: kind (required), index, duration.

document.set_textC

Replace the text on a text/auto-shape.

Inputs: text (required), shape_id (required).

document.undoB

Undo the most recent command.

Inputs: no named parameters.

document.ungroupB

Remove a Group wrapper. Pass either group_id or shape_id (any shape from the group).

Inputs: group_id, shape_id.

script.runB

Execute a Python string against the live Document. Bound names: document, slides, current_slide, undo_stack, rt (with add_text/add_rect/...), math, random, json. Imports, eval/exec, and dunder access are blocked.

Inputs: code (required).

script.sampleB

Return a sample script for the script editor.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 46 tools

    Disambiguation3/5

    Most tools target distinct slide, shape, document, or app operations, and descriptions clarify slide-level versus shape-level actions. However, there are several overlapping pairs: remove_slide versus delete_slides, copy_slide/paste_slide versus copy/paste for shapes, and duplicate_slide versus duplicate for shapes. These boundaries are inferable but create real misselection risk.

    Naming Consistency4/5

    Names consistently use a namespace.action snake_case convention such as document.get_slide, app.save_document_as, and clipboard.peek. Minor inconsistencies appear with remove_slide/delete_slides and shape clipboard tools named copy/cut/paste rather than copy_shapes/cut_shapes/paste_shapes, but the overall pattern is predictable.

    Tool Count2/5

    With 46 tools, the surface is very large for a slide-editing server and includes many granular operations that could be consolidated or handled through properties/scripting. While the breadth supports a full editor, the count is heavy enough to burden tool selection and maintenance.

    Completeness4/5

    The server covers document lifecycle, slide CRUD/duplication/reordering, shape CRUD/grouping/alignment/z-order, text and property editing, clipboard operations, export, and undo/redo. Minor gaps remain, such as inserting a slide at an arbitrary index, richer table/cell editing, and slide layout/master operations, but core workflows are complete.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Full-featured PowerPoint MCP server with cross-platform support (Windows native, macOS designed). Control PowerPoint programmatically via the Model Context Protocol — 153 tools covering slides, shapes, text, formatting, charts, tables, animations, and more.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables building and editing real PowerPoint decks from any MCP host with a live local browser studio, slide locks, human-only pause/resume/undo/redo controls, and export to PPTX, PDF, or PNG. It preserves imported decks in one editable model while requiring no model calls, accounts, or API keys.
      MIT