Skip to content
Back to search

ppt-mcp

The world's best PowerPoint MCP server. Real-time control of a live PowerPoint on Windows and macOS, 156 tools for AI agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/ykuwai/ppt-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/ykuwai/ppt-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ykuwai--ppt-mcp/badge.svg)](/listings/ykuwai--ppt-mcp)

HTML

<a href="/listings/ykuwai--ppt-mcp"><img src="/api/listings/ykuwai--ppt-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Standard config — works in Claude Desktop, Cursor, `.mcp.json`, and most other MCP clients:

{
  "mcpServers": {
    "powerpoint": {
      "command": "uvx",
      "args": ["ppt-mcp"]
    }
  }
}

Claude Code

**User-scoped** (available in all projects)

claude mcp add powerpoint uvx ppt-mcp

**Project-scoped** (stored in `.mcp.json`, shared with your team)

claude mcp add --scope project powerpoint uvx ppt-mcp

Cursor

Or add manually to `~/.cursor/mcp.json` using the standard config above.

Claude Desktop

Edit `%APPDATA%\Claude\claude_desktop_config.json` using the standard config above.

Codex

Edit `~/.codex/config.toml`:

[mcp_servers.ppt-mcp]
command = "uvx"
args = ["ppt-mcp"]

Or use the standard JSON config above in `.codex/config.json`.

VS Code

code --add-mcp '{"name":"powerpoint","command":"uvx","args":["ppt-mcp"]}'

From source

git clone https://github.com/ykuwai/ppt-mcp.git
cd ppt-mcp
uv sync
{
  "mcpServers": {
    "powerpoint": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\ppt-mcp",
        "run",
        "mcp",
        "run",
        "src/server.py"
      ]
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 505 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="https://raw.githubusercontent.com/ykuwai/ppt-mcp/main/assets/ppt-mcp-logo-letter.png" alt="PowerPoint MCP" width="480">
  3. </p>
  4. <p align="center">
  5. <strong>English (en)</strong> · <a href="i18n/README.ja.md">日本語 (ja)</a> · <a href="i18n/README.zh-CN.md">简体中文 (zh-CN)</a> · <a href="i18n/README.es.md">Español (es)</a> · <a href="i18n/README.pt-BR.md">Português (pt-BR)</a> · <a href="i18n/README.he.md">עברית (he)</a>
  6. </p>
  7. <p align="center">
  8. <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.10%2B-blue.svg" alt="Python"></a>
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"></a>
  10. <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS-0078d4.svg" alt="Platform">
  11. <a href="https://pepy.tech/projects/ppt-mcp"><img src="https://static.pepy.tech/personalized-badge/ppt-mcp?period=total&units=ABBREVIATION&left_color=BLACK&right_color=GREEN&left_text=downloads" alt="Downloads"></a>
  12. </p>
  13. <p align="center">
  14. <strong>Real-time PowerPoint control on Windows and macOS —<br>an MCP server with <!--tools-->157<!--/tools--> tools for AI agents and developers.</strong>
  15. </p>
  16. ---
  17. An MCP (Model Context Protocol) server that gives AI agents full control over a live Microsoft PowerPoint instance, over COM on Windows and Apple Events on macOS. Unlike file-based libraries like python-pptx, this server interacts directly with a running PowerPoint application.
  18. ## 🎬 Demo
  19. An agent building a deck in a live PowerPoint window (15x speed):
  20. https://github.com/user-attachments/assets/178b9b5b-624d-4de0-a1dd-619dc13d4bd7
  21. ## ✨ Key Features
  22. - **Real-time control** — Directly manipulates a running PowerPoint instance; changes appear instantly on screen
  23. - **Broad coverage** — Slides, shapes, text, tables, charts, animations, SmartArt, media, freeform paths, and more
  24. - **Safe for AI agents** — `ppt_activate_presentation` locks all tools to a specific file, preventing accidental edits to the wrong presentation
  25. - **[Google Material Symbols](https://fonts.google.com/icons) icons** — Search 2,500+ icons by keyword and insert as SVG with theme colors
  26. - **Theme color awareness** — Pass `accent1`, `accent2`, etc. wherever a fill, line, shadow, glow or text color is taken, instead of hardcoded RGB values; the shapes follow the theme when it changes
  27. - **Windows and macOS** — The same tools, arguments and return values on both; where PowerPoint for Mac cannot do something, the tool says so rather than quietly doing nothing
  28. ## 📋 Requirements
  29. - Windows 11, or macOS with Apple Silicon or Intel
  30. - Microsoft PowerPoint
  31. - [uv](https://docs.astral.sh/uv/getting-started/installation/)
  32. On macOS the server drives PowerPoint over Apple Events instead of COM. The
  33. first tool call raises the system's automation prompt, and PowerPoint has to be
  34. allowed there once. Pictures, icons, templates, themes, previews and exports
  35. pass through PowerPoint's own folder, which macOS 14 and later keeps other apps
  36. out of, so the application that launches the server (Terminal, an editor,
  37. Claude) needs Full Disk Access for those tools. Run from a terminal, macOS may
  38. refuse without asking; the tools then say what to grant. Shapes, text, tables
  39. and charts work regardless. See [macOS support](#-macos-support) for what
  40. differs.
  41. ## 🚀 Getting Started
  42. Standard config — works in Claude Desktop, Cursor, `.mcp.json`, and most other MCP clients:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "powerpoint": {
  47. "command": "uvx",
  48. "args": ["ppt-mcp"]
  49. }
  50. }
  51. }
  52. ```
  53. ### Claude Code
  54. **User-scoped** (available in all projects)
  55. ```bash
  56. claude mcp add --scope user powerpoint uvx ppt-mcp
  57. ```
  58. **Project-scoped** (stored in `.mcp.json`, shared with your team)
  59. ```bash
  60. claude mcp add --scope project powerpoint uvx ppt-mcp
  61. ```
  62. ### Cursor
  63. [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=ppt-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJwcHQtbWNwIl19)
  64. Or add manually to `~/.cursor/mcp.json` using the standard config above.
  65. ### Claude Desktop
  66. Edit `%APPDATA%\Claude\claude_desktop_config.json` using the standard config above.
  67. ### Codex
  68. Edit `~/.codex/config.toml`:
  69. ```toml
  70. [mcp_servers.ppt-mcp]
  71. command = "uvx"
  72. args = ["ppt-mcp"]
  73. ```
  74. Or use the standard JSON config above in `.codex/config.json`.
  75. ### VS Code
  76. ```bash
  77. code --add-mcp '{"name":"powerpoint","command":"uvx","args":["ppt-mcp"]}'
  78. ```
  79. ### From source
  80. ```bash
  81. git clone https://github.com/ykuwai/ppt-mcp.git
  82. cd ppt-mcp
  83. uv sync
  84. ```
  85. ```json
  86. {
  87. "mcpServers": {
  88. "powerpoint": {
  89. "command": "uv",
  90. "args": [
  91. "--directory",
  92. "C:\\path\\to\\ppt-mcp",
  93. "run",
  94. "mcp",
  95. "run",
  96. "src/server.py"
  97. ]
  98. }
  99. }
  100. }
  101. ```
  102. ## 🛠️ Tool Categories
  103. The full list of tools, by category, is in [TOOLS.md](TOOLS.md).
  104. ## 💡 Example Prompts
  105. Just describe what you want in plain language — no code required.
  106. ---
  107. **Simple** — topic only
  108. > *"Create a 3-slide intro deck for a productivity app called Flowly."*
  109. <details>
  110. <summary>View slides</summary>
  111. <br>
  112. <img src="assets/examples/example1/Slide1.png" width="640">
  113. <img src="assets/examples/example1/Slide2.png" width="640">
  114. <img src="assets/examples/example1/Slide3.png" width="640">
  115. </details>
  116. ---
  117. **With style direction** — topic + visual style
  118. > *"Make a 4-slide presentation on the benefits of async work. Dark navy style, add icons for each benefit."*
  119. <details>
  120. <summary>View slides</summary>
  121. <br>
  122. <img src="assets/examples/example2/Slide1.png" width="640">
  123. <img src="assets/examples/example2/Slide2.png" width="640">
  124. <img src="assets/examples/example2/Slide3.png" width="640">
  125. <img src="assets/examples/example2/Slide4.png" width="640">
  126. </details>
  127. ---
  128. **Detailed** — topic + design intent + slide structure
  129. > *"Build a 5-slide pitch for an AI note-taking app called NoteAI. White background, teal accent. Slides: title, problem, solution, features with icons, closing."*
  130. <details>
  131. <summary>View slides</summary>
  132. <br>
  133. <img src="assets/examples/example3/Slide1.png" width="640">
  134. <img src="assets/examples/example3/Slide2.png" width="640">
  135. <img src="assets/examples/example3/Slide3.png" width="640">
  136. <img src="assets/examples/example3/Slide4.png" width="640">
  137. <img src="assets/examples/example3/Slide5.png" width="640">
  138. </details>
  139. ---
  140. **Design keywords that elevate results:**
  141. | Aspect | Keywords / Phrases | What it does |
  142. |---|---|---|
  143. | **Icons** | `add icons` · `icon for each point` · `use icons throughout` | Searches Google Material Symbols and places crisp SVG icons automatically |
  144. | **Color scheme** | `dark navy` · `white background` · `monochrome` · `light gray` | Sets the overall color palette and mood |
  145. | **Accent color** | `teal accent` · `blue accent` · `brand color #2563EB` | Applies a specific highlight color to headings, icons, and shapes |
  146. | **Style tone** | `modern minimal` · `bold and vibrant` · `clean and professional` · `playful` | Signals the overall visual personality |
  147. | **Deck type** | `pitch deck` · `investor presentation` · `workshop slides` · `status report` | Guides layout and content density toward the intended purpose |
  148. | **Slide structure** | `Slides: title, problem, solution, features, CTA` · `4 slides` | Defines the narrative arc and slide count up front |
  149. | **Layout** | `card layout` · `two-column` · `centered` · `full-bleed background` | Shapes how content is arranged on each slide |
  150. | **Text density** | `minimal text` · `one message per slide` · `bullet points` | Controls how much text appears and how it's formatted |
  151. | **Backgrounds** | `gradient background` · `solid dark background` · `soft light background` | Specifies the background treatment across slides |
  152. | **Emphasis** | `highlight key numbers` · `bold headings` · `accent bar on each slide` | Draws attention to the most important information |
  153. ## 🔍 Features in Detail
  154. ### 🎯 Presentation Targeting
  155. `ppt_activate_presentation` sets a session-level target so every subsequent tool call operates on that specific file — regardless of which window is active in PowerPoint. Switch targets anytime by calling it again.
  156. ```python
  157. ppt_activate_presentation(presentation_name="report.pptx")
  158. # All tools now operate on report.pptx
  159. ppt_activate_presentation(presentation_name="demo.pptx")
  160. # Switched — all tools now operate on demo.pptx
  161. ```
  162. The activated presentation is one value for the whole server, and a client such as Claude Desktop routes every conversation through one server. When several conversations work on different files at once, pass `presentation` on each call. It applies to that call only, leaves the activated presentation alone, and accepts a full path, a file name, or a file name without extension. A file that is not open is an error, never a fallback to another one.
  163. ```python
  164. ppt_add_textbox(params={...}, presentation="report.pptx")
  165. # Lands in report.pptx whatever another conversation has activated
  166. ```
  167. ### 👥 Files Others Edit at the Same Time (Windows)
  168. A presentation opened from SharePoint or OneDrive can be edited by other people while the server works on it. Without AutoSave, PowerPoint takes in what they have saved only when the file is saved, and shows "Updates available" until then; the server would read and write the older state. The server handles that for such a file:
  169. - **Before a tool call** it merges the others' changes, as long as nothing in this copy is unsaved, so a read sees the current state. A writing call whose slides or shapes the merge moved is refused without changes, because its indices came from the older state.
  170. - **Results** carry `coauthoring`: `pending_updates` (changes wait; `ppt_save_presentation` takes them in), `merged_updates` (they were just merged), `conflict`. `ppt_open_presentation`, `ppt_activate_presentation` and `ppt_get_presentation_info` always report it, with `coauthor_count`; `ppt_list_presentations` gives `pending_updates` per file.
  171. - **A conflict** (both sides changed the same object) opens PowerPoint's "Resolve conflict" dialog, which the object model cannot answer, so it stays with the user. An integration can answer it instead: `utils.coauthoring.set_conflict_resolver(fn)` registers a function that gets the Presentation on the COM thread and returns `True` once the dialog is answered; the result then lists in `overwritten` each slide that now differs from this copy's version, with the text it had here.
  172. ### 📁 Template Support
  173. Auto-detects your personal PowerPoint templates folder (registry, OneDrive, or default paths). Use `ppt_list_templates` to discover available templates, then `ppt_create_presentation(template_path=...)` to create a new presentation from any template.
  174. ### 🎨 Google Material Symbols Icons
  175. Search 2,500+ [Google Material Symbols](https://fonts.google.com/icons) icons with `ppt_search_icons(query="...")` and insert them as SVG with `ppt_add_svg_icon`:
  176. - **3 styles**: outlined, rounded, sharp
  177. - **Filled variants**: set `filled=True`
  178. - **Theme colors**: `color="accent1"` uses the presentation's accent color
  179. - **Auto-fit**: preserves aspect ratio within the specified area
  180. ### ⚡ Real-Time Navigation
  181. Every write operation automatically navigates PowerPoint to the target slide. You see changes happening in real-time — no need to manually switch slides.
  182. ### ✍️ Text Formatting
  183. - `\n` — Paragraph break (Enter). Each paragraph gets its own bullet/indent level.
  184. - `\v` — Line break (Shift+Enter). Stays in the same paragraph, preserving formatting.
  185. - Per-character formatting with `ppt_format_text_range`
  186. - Auto-fit control: shrink text to fit, resize shape, or overflow
  187. ### 🎨 Theme Color Presets & Auto-Generation
  188. `ppt_set_theme_colors` supports three modes:
  189. - **17 curated presets** — WCAG AA accessible palettes across 5 categories: Classic (`corporate_blue`, `executive`, `consulting`), Design Systems (`tailwind`, `chakra`, `open_color`, `radix`), Nature (`ocean`, `forest`, `sunset`, `sage`), Modern (`nord_light`, `pastel_deep`, `swiss`), Vibrant (`vivid`, `rainbow`, `neon_safe`)
  190. - **Primary color generation** — provide a single brand color (`primary="#2B579A"`) to auto-generate a full harmonious palette using color harmony (split-complementary + analogous)
  191. - **Manual** — set individual color slots (`accent1`, `accent2`, etc.)
  192. Modes can be combined: use a preset as a base and override specific slots. All accents are guaranteed 3:1+ contrast on white.
  193. ### 🔍 Typography Check
  194. `ppt_check_typography` detects and optionally auto-fixes common typography issues:
  195. - **Widow lines** — isolated 1-3 character lines caused by word wrapping
  196. - **Short lines after soft returns** — side effects of manual line breaks (`\v`)
  197. - **Auto-shrunk text** — text silently compressed by PowerPoint's shrink-to-fit feature
  198. Auto-fix strategies include widening text boxes and inserting soft returns.
  199. ### 📐 Layout Check
  200. `ppt_check_layout` measures a slide, or the whole deck, and reports what is wrong as numbers rather than as a picture, so it works whether or not the model can read images:
  201. - **Off the slide** — a shape, or its text, reaching past a slide edge
  202. - **Overflow** — text that needs more room than its box gives it
  203. - **Overlap** — text running into another shape or into other text, text over a table's cells or hidden under a card laid over it, and anything a slide adds running into or across the template's own graphics: its logo, a band down the side, a footer line, the rule under the title
  204. - **Low contrast** — text against what is behind it, below the WCAG minimum for its size, on a gradient too, and on a photo against the part of the photo under it
  205. - **Cramped text** — text on a card pressed against one of its edges
  206. - **Narrow margin** — a shape closer to the side of the slide than the margin the rest of the slide keeps, or run almost to its top or bottom
  207. - **Title edge** — a title whose words start a few points from where the body below it starts, which reads as two edges a little apart
  208. - **Misaligned** — edges a few points apart that were meant to line up
  209. - **Uneven spacing** — a row or column of like shapes with unequal gaps
  210. - **Uneven sizes** — like shapes in a row that are not one height, or in a column not one width, and a row with one card a little wider than the rest
  211. - **Sample text** — lorem ipsum, "Your title here", "[Company name]" or "XX%" left behind by a template or a draft, and a chart still holding the data PowerPoint puts in a new one
  212. - **Stretched pictures** — a picture or logo drawn in other proportions than its image; the fix puts them back, or crops the picture to its box with `ppt_crop_picture crop_fit`
  213. - **Small text** — text under 10 pt, which a projected slide loses, measured at the size PowerPoint draws text it shrinks to fit
  214. - **Blurry pictures** — a picture drawn larger than its image has pixels for
  215. - **Charts** — data labels running into each other, or a legend or title lying on the plot. Windows only: PowerPoint for Mac has no chart object to read
  216. - **Alt text** — a picture, chart or SmartArt graphic a screen reader cannot describe. `ppt_update_shape alt_text` sets it on Windows; PowerPoint for Mac does not let a tool set it, so there it is set by hand
  217. - **Fonts** — text in a font this computer does not have, so PowerPoint draws it in a stand-in, and Hebrew or Arabic drawn in another font than the one asked for
  218. - **Right-to-left text** — on a Hebrew or Arabic slide, a line of numbers only, such as "1948–1967", which PowerPoint draws left to right and a reader reads backwards, and a paragraph left to right in a file another program wrote. `ppt_set_paragraph_format direction='rtl'` sets a paragraph's direction and keeps the side it is aligned to
  219. - **Empty placeholders**, and, for the whole deck, **titles** that change size, position, alignment, weight, typeface or colour from slide to slide, or are typed in capitals among titles in normal case, **body text** a size or two off the rest of the deck's, and slides with **no title** or **the same title** as another, which a screen reader and the outline cannot tell apart. A right-aligned title, as in a Hebrew or Arabic deck, is compared on its right edge, and a title on a layout no other slide uses is held to where its layout puts it
  220. Shapes inside groups and SmartArt graphics are checked for what their text says and how it is set: overflow, contrast, sample text, fonts, direction and size.
  221. A slide is judged as the slide show draws it. Lines a build-up shows one at a time in one place do not overlap, a shape a motion path moves is judged where it goes, a sound's icon dragged off the slide is hidden on purpose, and a shape waiting off a slide next to a Morph transition is left there. A finding on a hidden slide says that it is hidden.
  222. Each issue names the shapes and says how to fix it, with the tool call and its values. A fix keeps the slide together rather than only clearing the issue: a card grows with its padding and the rest of its row, and a shape brought back onto the slide keeps the slide's margin. The tools that add, copy, move, resize, align, distribute or retext a shape, or fill a placeholder, also check the shape they touched and report any problem in their own result, under `layout_issues`, so it is caught by the call that caused it. A new slide background, or a new fill under text, reports the text it left hard to read, and a change to the whole deck, its theme, theme colours, fonts or slide size, reports what it broke that was not broken before.
  223. Each of those checks reads the slide back, which adds a moment to every write, more on the Mac. To leave the checking to `ppt_check_layout` alone, set `PPT_LAYOUT_CHECKS=off` in the server's `env`; the server's instructions then tell the model to run it after each few changes. The accepted values are `on` (the default) and `off`; anything else is ignored with a warning and the checks stay on. A change to the whole deck (theme, theme colours, font, default fonts, slide size) reads every slide before and after. On a deck of more than 300 shapes it reads neither, since that would take longer than the change, and says so under `layout_check_skipped`, leaving the deck to `ppt_check_layout`. Paragraph formatting, bullets, picture crops and formats, grouping, SmartArt, chart data, lines, deleting table rows and columns, splitting cells and copying slides are checked the same way. A slide copied into another open deck is not: the check reads the deck the server is working on.
  224. On a deck made from a template, the template is part of the check. The graphics its slide master and layouts draw are read, so a chart sized over the logo or a footnote on the confidentiality line is reported, and what the template designed is taken as meant: a placeholder still in the theme's colours, or a caption layout's own smaller title, is not held to the rest, and in a deck on two designs each design's titles are compared only with each other. Theme colours set with `ppt_set_theme_colors` are the caller's, so that call judges the placeholders in them too, and so does every later check once the theme's own text colour no longer reads on its background. PowerPoint for Mac exposes the master's graphics but not a layout's own, nor what is inside a group, so there the layout's graphics, its title's place, the theme's fonts and the text inside groups are read from the deck's saved file, while it holds what is on screen. On a deck not yet saved, or changed since, a layout's design is allowed for through its placeholders.
  225. ## ⚙️ Advanced Configuration
  226. ### Handling PowerPoint Modal Dialogs
  227. When PowerPoint has a modal dialog open (e.g., SmartArt layout picker, Save dialog, Insert dialog), COM calls return `RPC_E_CALL_REJECTED`. The MCP server **automatically retries for up to 15 seconds** (5 retries × 3 s), so the server stays connected and responsive even when a dialog is blocking PowerPoint.
  228. **Auto-dismiss (opt-in):** By default, the server waits for you to close the dialog manually. To have the server automatically send ESC on the first retry — dismissing the dialog without user interaction — set `PPT_AUTO_DISMISS_DIALOG=true`:
  229. ```json
  230. {
  231. "mcpServers": {
  232. "powerpoint": {
  233. "command": "uvx",
  234. "args": ["ppt-mcp"],
  235. "env": {
  236. "PPT_AUTO_DISMISS_DIALOG": "true"
  237. }
  238. }
  239. }
  240. }
  241. ```
  242. ESC cancels without committing, so there are no destructive side effects. This is particularly useful in automated workflows where no human is present to close dialogs.
  243. ### PowerPoint that the server starts
  244. If no PowerPoint is running when a tool needs one (`ppt_create_presentation`, `ppt_open_presentation`, `ppt_connect`), the server starts it. On macOS it starts in the background and does not take the front from the app you are working in.
  245. When a close leaves no presentation open in a PowerPoint the server started, `ppt_close_presentation` quits PowerPoint too and says so (`powerpoint_quit`). A PowerPoint you started yourself is never quit, and neither is one that still has a presentation open (on Windows, or a file open in Protected View). Pass `keep_powerpoint_open=true` to keep it running, for example to open another presentation straight away. Until a tool starts PowerPoint again, tools that need it answer that PowerPoint is not running, where they would otherwise have reported an empty list. On Windows, a file open in Protected View is listed by `ppt_list_presentations` under `protected_view`, and `ppt_close_presentation` closes it by its name, without saving.
  246. ### Working in the same deck as the model
  247. Each write moves the deck's window to the slide it works on, so you can see where the model is. To work in the deck yourself at the same time, without the window jumping to another slide, set `PPT_FOLLOW_EDITS=off` in the server's `env`. The edits land the same way; only the window stays where you left it. `ppt_goto_slide` still moves it when asked. The accepted values are `on` (the default) and `off`; anything else is ignored with a warning. While you are typing in a text box PowerPoint may hold the model's call for a moment, and undo (Ctrl+Z) is shared, so it can take back the model's last change.
  248. ```json
  249. "env": { "PPT_FOLLOW_EDITS": "off" }
  250. ```
  251. ### Icons on a network that blocks the icon sites
  252. `ppt_search_icons` reads its icon list from `fonts.google.com`, and `ppt_add_svg_icon` downloads icons from `cdn.jsdelivr.net`. Every download, pictures by URL included, gives up after 15 seconds and says which host it could not reach. Three settings change that:
  253. | Setting | Default | What it does |
  254. |---|---|---|
  255. | `PPT_ICON_BASE_URL` | `https://cdn.jsdelivr.net/npm/@material-symbols/svg-400@0.31.3` | Where icons come from. Any address with the package's layout (`<base>/outlined/home.svg`) works: a mirror such as `https://unpkg.com/@material-symbols/svg-400@0.31.3`, or a local copy of the package as `file:///path/to/svg-400`. |
  256. | `PPT_ICON_METADATA_URL` | `https://fonts.google.com/metadata/icons` | Where the icon list comes from. Save that page once and point this at the copy, as `file:///path/to/icons.json`. |
  257. | `PPT_DOWNLOAD_TIMEOUT` | `15` | Seconds to wait for a server to answer. A value that is not a positive number is ignored (15 is used). |
  258. ```json
  259. {
  260. "mcpServers": {
  261. "powerpoint": {
  262. "command": "uvx",
  263. "args": ["ppt-mcp"],
  264. "env": {
  265. "PPT_ICON_BASE_URL": "https://unpkg.com/@material-symbols/svg-400@0.31.3"
  266. }
  267. }
  268. }
  269. }
  270. ```
  271. ### The tool list: catalog mode
  272. A client sends the description of every tool it lists with every request, and this server's tools come to about 112k tokens, a large part of a 128k or 200k window before any work. By default the server lists three tools instead, about 700 tokens, and the model reaches the rest through them:
  273. | Tool | What it does |
  274. |---|---|
  275. | `ppt_describe` | With no names, the list of all the tools, one line each. With names, their full description and arguments. |
  276. | `ppt_run` | Runs one tool: `{"tool": "ppt_add_textbox", "params": {...}}`. |
  277. | `ppt_run_steps` | Runs several in order, in one call. A step can use what an earlier one answered: `"$prev.shape_name"` is the previous step's `shape_name`, `"$2.shape_name"` the second step's. The first step that fails ends the run and says why. |
  278. The tools themselves are the same, with the same arguments, checks and answers, and `presentation` is passed the same way. The model asks `ppt_describe` before using a tool for the first time, which costs one call. Building the same 12-slide deck through Claude Code, the context peaked at 136k tokens in catalog mode against 206k with every tool listed, and the run cost a third less.
  279. What catalog mode gives up is per-tool control in the client: approving or blocking a tool by its name, and its read-only hint, apply to the three tools above rather than to each one. A client that relies on that sets `PPT_TOOL_MODE=full` in the server's `env`, and every tool is listed by its own name, as below; `PPT_TOOL_MODE=catalog` is the default. A value other than `catalog` or `full` is ignored with a warning, and catalog mode is used.
  280. ```json
  281. {
  282. "mcpServers": {
  283. "powerpoint": {
  284. "command": "uvx",
  285. "args": ["ppt-mcp"],
  286. "env": { "PPT_TOOL_MODE": "full" }
  287. }
  288. }
  289. }
  290. ```
  291. ## 🍎 macOS support
  292. **With the VBA add-in, on by default, 3 tools refuse on macOS; without it, <!--mac-refusals-->10<!--/mac-refusals--> do. The rest work.** The <!--mac-refusals-->10<!--/mac-refusals--> are listed by name in
  293. [MACOS_PORT.md](MACOS_PORT.md) section 6.1, and a test keeps that list honest.
  294. The same tools, the same arguments, the same answers. What differs is what
  295. PowerPoint for Mac's scripting dictionary can reach, and where it cannot reach
  296. something the tool says so rather than doing something unexpected.
  297. **PowerPoint for Mac's VBA reaches further.** The
  298. server loads a small add-in, `ppt-mcp-bridge`, into PowerPoint and runs the
  299. Windows code through it for what the scripting dictionary has no words for:
  300. tags, `ppt_select_shapes`, `ppt_set_table_style`, removing and copying one
  301. animation, a freeform node's editing type, the chart formatting, axis, series, type and
  302. data tools (the data
  303. through the chart's Excel workbook, which opens in Excel for a moment, as on
  304. Windows), the freeform node
  305. tools and grouping, text inside a group, a template's layouts by name,
  306. duplicating and copying slides, editing a SmartArt (its text, nodes, colours
  307. and style), and the arguments the Mac otherwise refuses (a screen tip,
  308. a table row or column at a position, a click trigger on another shape,
  309. reflection sizes, glow, shadow and reflection on text, shrinking text to fit,
  310. volume, mute, trimming and fades, a chart style and the legend and title placement).
  311. Those edit the shape in place, so it keeps its animations, and the clipboard is
  312. not touched. The add-in only passes those calls on; its source is in
  313. `src/backend/vba`. PowerPoint loads it without a prompt and keeps it until PowerPoint quits;
  314. a copy of the file stays in PowerPoint's own folder. While it is loaded, other
  315. programs allowed to control PowerPoint can call it too, but only within
  316. PowerPoint's object model, and it refuses to run macros, quit or reach add-ins. Where it cannot be loaded,
  317. where macros are turned off by policy for instance, the tools work as described
  318. below. macOS may ask whether the app that runs the server may reach data
  319. from other apps; allow it, as the add-in answers through PowerPoint's folder.
  320. Until it is answered, or if it is refused, the tools work as described below
  321. after a two-second wait. It is on by
  322. default; `PPT_MAC_VBA=off` in the server's `env` turns it off. A call the
  323. add-in would have taken then says so, in its `hint` or `warnings`, as it does
  324. when the add-in cannot be loaded.
  325. Not available on macOS:
  326. - **`ppt_execute_mso`**, and without the add-in also **a freeform node's
  327. editing type** (move the node's handles instead), **tags,
  328. `ppt_select_shapes`, `ppt_set_table_style` and removing one animation**
  329. (clearing a slide's animations works). Nothing in the dictionary reaches them.
  330. Smaller differences:
  331. - **Call the tools one after another, not several in the same turn.** Only one
  332. request at a time reaches PowerPoint, so the rest queue behind it and come
  333. out in whatever order they arrived. A call left waiting too long is taken
  334. back and says so, having changed nothing.
  335. - Without the add-in, a few tools accept an argument that has no counterpart,
  336. a screen tip on a hyperlink for instance. Those refuse with a message naming
  337. the argument, so dropping it and retrying works.
  338. - **Video and audio go in embedded, never linked**, and of the eight playback
  339. settings only looping and hiding the frame exist, and with the add-in volume,
  340. mute, trimming and fades. Hiding the frame is refused on a slide that already has
  341. animations, because writing it rewrites them.
  342. - Exports are staged through PowerPoint's own container and moved out, because
  343. the application is sandboxed and cannot write to arbitrary folders.
  344. - **Without the add-in, a template's own layouts are found by name in the
  345. deck's saved file**, so save a new deck before asking `ppt_add_slide` for one
  346. by name. PowerPoint for Mac names no layouts to a script, so the slide is
  347. pasted in on its layout, which takes about a second. With the add-in the
  348. layout is found in the open deck, saved or not.
  349. - Slide images are rendered from a PDF rather than exported as PNG. A preview
  350. is 2 pixels per point on both platforms.
  351. - Automation consent belongs to whichever application launched the server, so
  352. running it from a different terminal or editor raises the prompt again.
  353. - Save the deck early and at each break. It costs nothing, and PowerPoint has
  354. been seen to close every open document and then exit when a sandbox prompt
  355. went up behind a script ([#191](https://github.com/ykuwai/ppt-mcp/issues/191)).
  356. - **Adding a chart goes through the clipboard**, and without the add-in so do
  357. the other chart tools, freeform paths and grouping.
  358. The operation takes the clipboard for a moment and puts back what was there.
  359. This is how they reach a dictionary that has no words for them. PowerPoint
  360. for Mac pastes into its front window, so with two decks open these work on
  361. the deck in front; for the other, the tool says so and changes nothing, and
  362. `ppt_activate_presentation` brings it to the front.
  363. - **Without the add-in, editing an existing chart or path recreates the
  364. shape**, and with it, setting a bubble chart's sizes still does. The tool copies the
  365. shape, rewrites it and pastes it back, then deletes the original. The name,
  366. position and z order are kept; animations on the shape are not, and the
  367. result says how many were lost. Without the add-in, a few formatting
  368. arguments that depend on the chart's rendered size (`chart_style`, legend and
  369. title coordinates, the 8-direction legend presets) are refused by name.
  370. - **Text inside a group** is reached by the member's name, or by its path
  371. (`"Group 4/TextBox 3"`), with `ppt_set_text` (the whole text, or a span
  372. inside one line) and `ppt_format_text`. With the add-in the member is edited
  373. in place. Without it the group is copied, the member rewritten and the group
  374. pasted back: the members keep their names, and the group loses its
  375. animations, as above.
  376. - Icons are rasterised with `sips` before they are inserted, because
  377. PowerPoint for Mac cannot read an SVG. That needs macOS 13 or newer; older
  378. systems get a refusal naming the reason rather than a blank box.
  379. ## 🤝 Contributing
  380. Pull requests are welcome. Base them on `develop`, one topic each, with tests; [CONTRIBUTING.md](CONTRIBUTING.md) has the rest.
  381. ## 📄 License
  382. MIT
  383. ## 🙏 Credits
  384. - [FastMCP](https://github.com/jlowin/fastmcp) — Pythonic MCP server framework
  385. - [pywin32](https://github.com/mhammond/pywin32) — Windows COM automation
  386. - [appscript](https://github.com/hhas/appscript) — macOS Apple Event bridge
  387. - [Model Context Protocol](https://modelcontextprotocol.io/) — by Anthropic

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.