# Office MCP

> Use when reading or editing the user's open Microsoft Word, Excel, or PowerPoint documents on macOS through the office MCP tools (word_*, excel_*, ppt_*, run_applescript). Covers the read -> edit -> screenshot workflow, tool conventions (1-based indexes, [r,g,b] colors, sheet param), the composite tools to prefer, and what AppleScript can't do.

- Skill: `charliecpeterson/office-mcp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add charliecpeterson/office-mcp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/charliecpeterson/office-mcp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: charliecpeterson (https://skillmd.com/u/charliecpeterson)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/charliecpeterson/office-mcp

---


# Driving Office with office-mcp

These tools edit the Microsoft Office documents the user **already has open** on
macOS, live (via Apple events). Each app is a separate MCP server (`word`,
`excel`, `powerpoint`); the connected server's tools are prefixed `word_*` /
`excel_*` / `ppt_*`. Every server also exposes `run_applescript` (escape hatch)
and `*_screenshot`.

## Core workflow: read -> edit -> see

1. **Read first** — `*_status` to confirm the app/document is open, then read the
   relevant content (`word_get_document_text`, `excel_read_range`,
   `ppt_read_slide`) so you act on real indices/values, not guesses.
2. **Edit** with the most specific tool.
3. **Verify visually** — call `*_screenshot` after any layout/format change and
   look at the result. Don't assume; confirm.

## Conventions

- Indexes (slides, shapes, paragraphs, tables, rows) are **1-based**.
- Colors are `[r, g, b]`, 0-255.
- Excel ranges are A1-style; most Excel tools take an optional `sheet` (name) —
  omit for the active sheet, pass it to work **across tabs**. Reads return 2-D lists.
- Prefer the **composite tools** for common multi-step tasks (fewer calls, more
  reliable — especially for smaller models):
  - `word_add_section(heading, body, level)` — styled heading + paragraph.
  - `excel_write_table(start_cell, values, header)` — values + header + borders + autofit.
  - `ppt_add_content_slide(title, bullets)` — a titled, bulleted slide.

## Per-app notes

- **Word**: editing is **paragraph-anchored** — read `word_get_paragraphs` to get
  the index, then `word_insert_paragraph(after=N or before=N, style=…)`,
  `word_replace_paragraph(N, …)`, `word_delete_paragraph(N)`. `word_get_paragraph(N)`
  gives one paragraph's full text. `word_insert_text` only appends at the end;
  `word_insert_at_cursor` / `word_replace_selection` act at the live cursor.
  `word_get_stats` for page/word counts (no screenshot). Build with `word_add_section`
  and `word_insert_table(data=…)` / `word_fill_table`. `word_find_replace` caps the
  replacement at 255 chars — use the paragraph tools for bigger text.
- **Excel**: formatting via `excel_format_range`; structure via
  `excel_insert_rows`/`_columns`, `excel_sort`, `excel_autofilter`,
  `excel_set_borders`, `excel_create_chart`; sheets via `excel_add_sheet` etc.
- **PowerPoint**: PowerPoint **can't report which shape is selected** — take a
  screenshot to see it. Reveal-on-click = `ppt_add_animation(..., exit=True)` on a
  cover shape. Add objects with `ppt_add_textbox` / `ppt_add_image`.

## Not possible (don't attempt — they error in the dictionary)

- PowerPoint: duplicating slides, creating charts, creating tables on slides.
- Word: comments.

Do these manually or tell the user. For anything else uncovered, use `run_applescript`.

## Permissions

First use of an app prompts a macOS **Automation** grant on the terminal app
(each app prompts once). The `*_screenshot` tools also need **Screen Recording**
(separate prompt, takes effect only after the terminal restarts). A denial returns
a clear "not authorized" error — guide the user to System Settings -> Privacy &
Security.