Let AI Agents Edit Office Files (2026)

TL;DR + what you actually need

OfficeCLI is a free, Apache-2.0 command-line tool that gives an AI agent direct read/write access to Word, Excel, and PowerPoint files — no Microsoft Office installation required. It ships two integration surfaces for the same binary: a built-in MCP server (Model Context Protocol — the JSON-RPC wire format Claude, Cursor, and other clients use to call external tools) that a client talks to directly, and an Agent Skill that teaches a bash-capable agent to shell out to the CLI itself.

• One binary, three formats: a self-contained executable (the .NET runtime is embedded) that creates, reads, modifies, and validates .docx, .xlsx, and .pptx files. No Office, no LibreOffice, no python-docx.
• A render engine that closes the loop: officecli view file.pptx screenshot produces a real PNG of the rendered document, so an agent can look at its own output instead of guessing from the XML.
• No auth, no cloud: everything runs against local files. The only network call is an optional version check.

The copy-paste MCP config, if that’s all you came for:

{
  "mcpServers": {
    "officecli": {
      "command": "officecli",
      "args": ["mcp"]
    }
  }
}

That assumes the officecli binary is already on your PATH — the install section below covers that in one line. If your job is specifically editing Word documents with track changes and comments, also read the docx-cli section — it’s a narrower, Word-only tool with a different (and benchmarked) approach.

Why this is a hard problem

A .docx, .xlsx, or .pptx file is a ZIP archive of XML parts — the format is called OOXML (Office Open XML). The default way an agent edits one is to unzip it, hand-write the XML changes, and re-zip. That works for trivial edits and falls apart fast: a strong model can just barely keep the markup valid, a weak one routinely produces a file Word refuses to open, and the whole process burns tokens re-deriving OOXML syntax the model has seen relatively little of during training.

Worse, the agent is blind. It can write <a:off x="720000" y="1800000"/> into a slide’s XML, but it has no way to tell whether that actually puts the text box where it meant to, or whether two shapes now overlap. Commenter wongarsu put the failure mode precisely on OfficeCLI’s Hacker News launch thread: even a capable model generating a PowerPoint deck spends most of its time not on the first version, but on rendering the result, looking at it, and adjusting alignment and contrast until it’s actually presentable — and that loop is exactly what breaks when the agent has no way to see the file it just wrote.

MCP.Directory already lists a few narrower answers to half of this problem — wrappers around python-docx and python-pptx like /servers/office-word and /servers/office-powerpoint, which expose those libraries as MCP tools but inherit their scriptable-but-blind nature. OfficeCLI and docx-cli take a different approach: a purpose-built binary that understands the file format directly and, in OfficeCLI’s case, can render what it just wrote back to an image.

What OfficeCLI actually does

OfficeCLI’s shape is a three-layer command architecture — start simple, drop down a layer only when you need to:

Layer 2 is where nearly everything happens, and it works by path-based element access: every shape, paragraph, cell, and slide has an address like /slide[1]/shape[2], and get/set/add take that path plus --prop flags instead of requiring the model to construct OOXML by hand. Output is deterministic JSON when you pass --json, which matters more than it sounds — a model parsing a stable, typed response makes fewer mistakes than one parsing prose.

Sitting underneath all three layers is a from-scratch HTML/PNG rendering engine, built into the binary rather than shelling out to Office or a headless browser plugin. That’s the piece that closes the render→look→fix loop from the previous section, and it’s covered with real output in the capabilities section below.

Two more pieces worth having in your mental model before you install anything:

• Resident mode. Opening a document with create or open keeps it loaded in memory across subsequent commands, so a chain of edits doesn’t re-parse the whole file each time. You save or close to flush to disk.
• Two integration surfaces. The built-in MCP server exposes every operation as a JSON-RPC tool for clients that speak MCP. The Agent Skill (a SKILL.md file OfficeCLI auto-installs into detected agent config directories) teaches a bash-capable agent — Claude Code, for instance — to call the CLI directly. Same binary, two different wires.

Our take: for a bash-capable coding agent, the skill path is usually the leaner option — the agent already has shell access, and officecli --help is self-documenting. Reach for the MCP server when your client doesn’t expose a shell — Claude Desktop, or an MCP-only integration in Cursor or VS Code.

Install: MCP server

OfficeCLI’s MCP server is built into the same binary you install for the CLI — there’s no separate package. Get the binary first (one line, covered in the next section), then register it. There are two paths:

The fast path — four supported clients

officecli mcp <target> writes the registration directly into a supported client’s config for you:

officecli mcp claude       # Claude Code
officecli mcp cursor       # Cursor
officecli mcp vscode       # VS Code / Copilot
officecli mcp lms          # LM Studio
officecli mcp list         # check registration status

We ran officecli mcp list against a clean install and got exactly the status table you’d expect before registering anything:

officecli MCP registration status:

  ✗ LM Studio       not registered
  ✗ Claude Code     not registered
  ✗ Cursor          not registered
  ✗ VS Code         not registered

Worth flagging: those are the only four auto-register targets. Claude Desktop is not one of them — for Desktop, Windsurf, or any other MCP client, use the manual JSON path below.

The manual path — every other MCP client

Because officecli mcp (bare, no target) starts the MCP stdio server directly, any client that reads a standard mcpServers block can launch it the same way Claude Code or Cursor would launch an npx-based server:

{
  "mcpServers": {
    "officecli": {
      "command": "officecli",
      "args": ["mcp"]
    }
  }
}

Drop that into claude_desktop_config.json, your Windsurf MCP config, or wherever your client keeps its server list. No environment variables, no API key — the tool needs nothing but a file path.

For Claude Code specifically, the one-liner is equivalent to the auto-register command above and keeps the server scoped to your shell config:

claude mcp add officecli -- officecli mcp

Full per-client config paths and flags: /clients/claude-code · /clients/cursor. New to MCP itself? /blog/what-is-mcp covers the protocol from first principles.

Install: the CLI (and the skill file)

OfficeCLI ships as a self-contained binary — the .NET runtime is embedded, so there’s nothing else to install:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/iOfficeAI/OfficeCLI/main/install.ps1 | iex

# or via a package manager
brew install officecli
npm install -g @officecli/officecli

We ran the curl installer, then confirmed it with officecli --version, which printed a plain version string with no other output — a good sign for scripting, since it means nothing else fires on a flag-bearing invocation.

After the binary is on your PATH, run:

officecli install

This detects which AI tools you have — Claude Code, GitHub Copilot, Codex, Cursor, Windsurf, and more — by checking their known config directories, and installs the officecli skill file into each one it finds. From that point, a bash-capable agent can call officecli commands directly without any MCP registration at all.

One behavior worth knowing before you script around this: per the README, a completely bare officecli invocation (no arguments) also triggers the install flow, same as the explicit install subcommand. If you’re wiring this into a CI step or a larger script, always pass a real subcommand — never call the bare binary expecting a no-op or a help message.

If you’d rather skip the installer and grab a binary straight from GitHub Releases yourself — which is what we did to test the commands in this guide — macOS Gatekeeper will flag it as unsigned. The official installer clears this for you automatically; doing it by hand is two commands:

xattr -d com.apple.quarantine ./officecli
codesign -s - -f ./officecli

Smallest end-to-end example

Every command below is a real transcript from testing this guide — nothing paraphrased. Creating a deck, adding content, and inspecting it:

$ officecli create deck.pptx
Created: deck.pptx (kept open in background for faster subsequent commands)
  totalSlides: 0
  slideWidth: 960pt
  slideHeight: 540pt

$ officecli add deck.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
Added slide at /slide[1]

$ officecli add deck.pptx '/slide[1]' --type shape \
    --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm \
    --prop font=Arial --prop size=24 --prop color=FFFFFF
Added shape at /slide[1]/shape[@id=100000]

$ officecli view deck.pptx outline
File: deck.pptx | 1 slides
├── Slide 1: "Q4 Report" - 1 text box(es)

$ officecli validate deck.pptx
Validation passed: no errors found.

Notice the very first line: create left the document open in the background without being asked — that’s resident mode kicking in by default, not an opt-in flag. We cover why that matters in Gotchas we hit, along with a positional-addressing surprise the get command handed us on this exact file.

Close the file when you’re done to flush it to disk and release the resident session:

$ officecli close deck.pptx
Resident closed for deck.pptx

Render loop, formulas, and template merge

Three capabilities carry most of OfficeCLI’s value over a plain OOXML-editing library. All three below were run against real files for this guide.

The render→look→fix loop

view has three output modes, and we tested the two static ones against the deck from the previous section:

$ officecli view deck.pptx html -o preview.html
→ preview.html (21.6 KB)

$ officecli view deck.pptx screenshot -o preview.png
[pages] total=1
→ preview.png (17.1 KB)

Both ran with no headless-browser setup on our end — the renderer is bundled into the binary. That’s the whole point: an agent can pipe a screenshot straight into its own context (or a vision-capable step) and check whether a title overflows or two shapes collide, instead of inferring layout correctness from raw coordinates. A third mode, watch, runs a local HTTP server that live-refreshes a browser preview on every edit — the same loop, interactive.

Formulas that evaluate on write

Excel cells compute immediately, with no round-trip through a spreadsheet application to recalculate. We wrote a formula and read it back in the same session:

$ officecli create budget.xlsx
$ officecli set budget.xlsx 'Sheet1!A1' --prop value=10
$ officecli set budget.xlsx 'Sheet1!A2' --prop value=32
$ officecli set budget.xlsx 'Sheet1!A3' --prop formula="=SUM(A1:A2)"
$ officecli get budget.xlsx 'Sheet1!A3' --json
{
  "success": true,
  "data": { "matches": 1, "results": [{
    "path": "/Sheet1/A3",
    "format": {
      "formula": "SUM(A1:A2)",
      "computedValue": "42",
      "evaluated": true
    }
  }]}
}

computedValue: "42" came back on the same call that wrote the formula — no separate recalc step. Per the README, this covers 350+ built-in functions, including spilling dynamic arrays (FILTER, SORT, LAMBDA) and financial functions (XIRR, DURATION). Native OOXML pivot tables are also one command — source range in, aggregated pivot out, written so Excel opens the file with the cache already populated.

Template merge for batch generation

merge replaces {{key}} placeholders in any .docx/.xlsx/.pptx with JSON data, across paragraphs, table cells, shapes, and headers:

officecli merge invoice-template.docx invoice-001.docx \
  '{"client":"Acme","total":"$5,200"}'

The design intent here is real: an agent designs the template once (the expensive, judgment-heavy step), and production code fills it N times afterward for zero additional tokens and deterministic output. That avoids the failure mode where an agent regenerates every report from scratch and produces N subtly different layouts. A related pair, dump and batch, serializes an existing document — or any subtree, like a single table or worksheet — into replayable JSON, so an agent can learn a template’s structure from a real example instead of raw XML.

docx-cli: the Word-only specialist

docx-cli (MIT-licensed, launched about seven weeks after OfficeCLI) does one job instead of three: reading, editing, and reviewing Word documents — leaving comments, suggesting redlines with track changes on, letting a human accept or reject in Word afterward. It has no Excel or PowerPoint support and, unlike OfficeCLI, it does not ship an MCP server — it’s a CLI plus an Agent Skill (a shared SKILL.md format that Claude Code, Codex, and other harnesses can all read), meant to be shelled out to directly.

Its core idea is stable locators instead of paths: text is addressed by character offset within a paragraph, like p3:5-20, so an agent can target “characters 5 through 20 of paragraph 3” without ever touching raw XML. The CLI mutates the underlying OOXML nodes in place and re-serializes, so anything it doesn’t model — custom styles, theme colors, schema extensions — survives untouched.

The maintainer, kirillklimuk, built it to help his wife, a professor, grade student submissions against an elaborate rubric — he described the origin story on both Hacker News and Reddit. The first version fixed broken output; later ones targeted speed and token cost, measured with a controlled A/B benchmark against “the default Claude skill” (Anthropic’s own reference Word-editing skill) across six real tasks — filling an NDA, redlining a contract, restyling a résumé, and similar — graded from the Word-rendered output by an independent judge. The maintainer’s self-reported numbers, three runs per arm:

Take the table as the author’s own reported bake-off, not an independently reproduced result — but it’s a specific, fixed, methodology-documented measurement, and the Reddit and Hacker News postings report the same numbers, for what that corroboration is worth. The qualitative claim underneath it is easy to check yourself: every docx-cli output opened cleanly in Word on the first try in the author’s tests, against 5 of 36 default-skill outputs that didn’t.

Filling and redlining an NDA, from the README:

docx replace mnda.docx "Fill in: today's date" "May 6, 2026"
docx track-changes mnda.docx on
docx replace mnda.docx "having a reasonable need to know" \
    "with a documented need to know"
docx comments add mnda.docx --at p7:0-30 \
    --text "Should we narrow 'representatives' to a named list?"

Install is a Claude Code plugin (/plugin marketplace add kklimuk/docx-cli then /plugin install docx-cli@docx-cli), a cross-harness install via skills.sh (npx skills add kklimuk/docx-cli), or a standalone binary with a SHA-256-verified installer script.

OfficeCLI vs docx-cli — which one

Reach for OfficeCLI the moment Excel or PowerPoint is in scope, or when you want a client to talk to it over MCP instead of shell access. Reach for docx-cli when the job is specifically Word review — fill a form, redline a contract, leave comments for a human — and you want the built-in --dry-run and the measured token savings on a cheap model. They’re not really competing for the same job; docx-cli is a scalpel for one document type and one workflow, OfficeCLI is the general-purpose suite.

Neither one overlaps with MarkItDown MCP, despite all three touching Office files. MarkItDown converts a document to Markdown — one direction only, read-only, built for getting a file into an LLM’s context or a RAG index. OfficeCLI and docx-cli go the other way: they read and write the native file, in place, formatting intact. If you need the reverse of MarkItDown — Markdown into a Word or PowerPoint file — that’s the md-to-office skill (built on Pandoc), a third, distinct tool for a third job.

Markitdownmicrosoft

Official1-Click Ready

Easily convert markdown to PDF using Markitdown MCP server. Supports HTTP, STDIO, and SSE for fast converting markdown to PDF workflows.

4.0k132

Gotchas we hit

Everything here is from testing this specific guide, not secondhand reports.

• Positional shape addressing isn’t what we assumed. We expected /slide[1]/shape[1] to be the shape we’d just added. It wasn’t — --prop title= on add slide auto-creates a title placeholder that occupies shape[1], and our explicit text box became shape[2] (confirmed by its actual assigned path, /slide[1]/shape[@id=100000]). Read the add command’s own output for the real path rather than assuming position.
• Resident mode is on by default, not opt-in. We expected to have to explicitly open a document to get resident-mode speed. Instead, create left it “kept open in background” automatically. That’s good for a chain of edits, but it means a live resident session can defer the disk write — the README is explicit that any non-officecli reader (Word, python-docx, an upload step) needs a save or close first, or it sees stale content.
• A bare invocation isn’t a no-op. Running officecli with zero arguments triggers the same auto-install flow as the explicit install subcommand, per the README. We avoided this by always passing a real subcommand in testing — worth the same discipline in any script or CI step that touches the binary.
• It phones home once, by default, for a version check. After a normal run, we found a ~/.officecli/config.json with a lastUpdateCheck timestamp — confirming the documented background auto-update check actually fires. Set OFFICECLI_SKIP_UPDATE=1 or officecli config autoUpdate false if you want the tool fully offline, e.g. in a sandboxed CI runner.
• The name itself drew real pushback. On the Hacker News launch thread, commenter neilv pointed out that branding the tool as simply “Office” while also warning against genericizing the trademark, in the same tagline, is an odd internal contradiction — and a reply from janalsncm noted Microsoft doesn’t need a legal reason to have a repo taken down. Not a technical risk, but a real one if you’re deciding whether to build production infrastructure around a young project’s current name.

Limits & safety

• No cloud, one exception. Both tools operate entirely on local files. OfficeCLI’s only network call by default is the version check above. docx-cli only reaches the network if you explicitly insert an image from an http(s) URL — and per its README, that fetch is bounded and “non-public / metadata addresses [are] refused at every redirect hop,” a deliberate guard against a common SSRF mistake in file-processing tools.
• There is no undo. Both tools mutate files in place. docx-cli’s own README says it plainly in its worked example: “there’s no undo (git is the history; the CLI overwrites in place).” Point either tool at a copy, or a git- tracked working tree, never at your only copy of a file that matters.
• The safety nets are different shapes. docx-cli ships --dry-run on every mutating command — simulate first, apply once you’ve read the diff. OfficeCLI has no equivalent flag we found; its safety net is validate and view issues after the fact, plus whatever version control you put around the file yourself.
• Blast radius is the whole file. Neither tool has a permissions model narrower than “whatever path you hand it.” Keep destructive operations behind your client’s tool-approval prompt the same way you would for any agent with local file write access.
• Cost: zero beyond your own compute. OfficeCLI is Apache-2.0, docx-cli is MIT, and neither project mentions a paid tier. Building from source ( optional — the shipped binaries are self-contained) needs the .NET 10 SDK for OfficeCLI or Bun 1.3+ for docx-cli; neither is needed at runtime.

Community signal

OfficeCLI’s launch drew a large Hacker News thread — 214 points and 63 comments — plus independent reactions on X. One thread from data engineer Charly Wargnier walked through exactly the capability that matters most for agent workflows: the render loop.

The launch thread wasn’t unanimous applause, which is exactly why it’s worth reading past the headline number. Beyond the naming critique covered in Gotchas we hit, several commenters pushed back on whether AI-generated Office documents are actually good yet — a fair question OfficeCLI’s render loop is a direct answer to, not a dismissal of.

docx-cli’s own launch was smaller — 69 points and 30 comments on its Show HN — and its maintainer cross-posted the same benchmark to r/claudeskills, where the reception centered on the numbers rather than the concept — unsurprising for a tool whose entire pitch is a measured comparison against the status quo.

The verdict

Frequently Asked Questions

Glossary

Sources

• Primary — OfficeCLI repository and README: github.com/iOfficeAI/OfficeCLI (Apache-2.0)
• Primary — docx-cli repository and README: github.com/kklimuk/docx-cli (MIT)
• Community — OfficeCLI Hacker News launch (214 points, 63 comments): “OfficeCLI: Office suite for AI agents to read and edit Microsoft Office files”, including the naming critique from neilv and janalsncm
• Community — docx-cli Show HN (69 points, 30 comments): “Show HN: Docx-CLI: agents read/edit Word docs using 1/2 the time and tokens”
• Community — docx-cli origin story and benchmark on Reddit: r/claudeskills
• Community — launch reaction on X: @DataChaz, July 8 2026
• All terminal output in this guide was captured directly against OfficeCLI v1.0.132 on macOS (arm64) while writing this post.
• Related guides: MarkItDown MCP · Claude pptx skill · What is MCP?
• Related catalog entries: /servers/markitdown · /servers/office-word · /servers/office-powerpoint · /skills/md-to-office