Office MCP

A local-first Model Context Protocol server for Microsoft Excel, Word, and PowerPoint files and applications.

This is an independent open-source project and is not affiliated with or endorsed by Microsoft.

Office MCP gives an orchestrating AI deterministic handles for Microsoft Office. It can work directly with .xlsx, .docx, and .pptx packages on any supported platform, or use the real installed Excel, Word, and PowerPoint applications on Windows for full-fidelity editing, calculation, charts, PivotTables, PDF export, and slide rendering. It runs locally over stdio and requires no API key.

The server does not decide what a report, model, or presentation should say. The model plans the work and calls these tools to inspect inputs, construct the documents, render the result, visually review it, and iterate.

Quick start (Windows PowerShell)

You need Node.js 20+, Git, and an MCP client such as Codex/ChatGPT desktop or Claude Code. Desktop Microsoft Office is optional for basic .xlsx, .docx, and .pptx file creation; it is required for Windows-native features such as animations and PowerPoint rendering. This repository is not yet published on npm.

1. Download and build the server:

   git clone https://github.com/gauravvvvvvvvvv/office-mcp.git
   Set-Location office-mcp
   npm ci
   npm run build

2. In the same PowerShell window, choose which files the AI may access and connect one client. This example allows your Documents folder; change $allowed to a narrower folder if you prefer:

   $entry = (Resolve-Path .\dist\index.js).Path
   $allowed = (Resolve-Path ([Environment]::GetFolderPath('MyDocuments'))).Path

   For Codex CLI or ChatGPT desktop, run:

   codex mcp add office --env "OFFICE_MCP_ROOTS=$allowed" -- node $entry
   codex mcp list

   For Claude Code, run instead:

   claude mcp add --scope user --env "OFFICE_MCP_ROOTS=$allowed" --transport stdio office -- node $entry
   claude mcp get office

3. Restart an already-open desktop client or start a new chat. Ask: “Call office_capabilities and tell me which Office features are available.” Then try: “Use powerpoint_create_designed_presentation to create a two-slide presentation in my Documents folder, inspect it, and report the saved path.” The server runs when the client launches it; do not start node dist/index.js in a separate terminal.

If you use both clients, run both registration commands. Existing office entries should be checked before re-adding them; codex mcp list and claude mcp get office show what is already configured. The checkout must remain at this path, because the clients launch its compiled dist/index.js. See other platforms and clients or troubleshooting below.

Related MCP server: MCP-OPENAPI-DOCX

Why this server

• Hybrid operation: portable Office-file creation and inspection without desktop Office, plus native Windows Office operations when installed.

• Prompt-specific quality contracts, file comparisons, render evidence, and a finalization gate that refuses stale or incomplete review.

• PowerPoint generation that stays in the background by default; it does not repeatedly steal focus from the user's work.

• Bounded filesystem roots, explicit overwrite behavior, and no arbitrary COM execution tool.

These are design choices, not proof that this project is more capable or produces better-looking documents than every alternative. Its 34-tool surface is intentionally bounded; a human-quality result still depends on the orchestrating model, source material, and visual review.

What works

The server exposes 34 MCP tools:

• office_capabilities

• office_inspect_file

• office_search_files

• office_convert_to_pdf

• office_export_pdf

• office_quality_check

• office_compare_files

• office_prepare_review

• office_finalize

• office_get_review_image

• excel_create_workbook

• excel_inspect_workbook

• excel_read_range

• excel_analyze_dataset

• excel_query_dataset

• excel_write_range

• excel_set_formulas

• word_create_document

• word_inspect_document

• word_append_paragraph

• word_replace_text

• powerpoint_create_presentation

• powerpoint_create_designed_presentation

• powerpoint_inspect_presentation

• powerpoint_audit_presentation

• powerpoint_inspect_template

• powerpoint_create_from_template

• powerpoint_replace_text

• office_native_status

• office_list_open_files

• excel_native_batch

• word_native_batch

• powerpoint_native_batch

• powerpoint_render_presentation

Requirements

• Node.js 20 or newer

• Microsoft Office on Windows for native automation, active-document control, and PowerPoint rendering

• LibreOffice only for portable PDF conversion when native Office is unavailable

Microsoft Office does not need to be installed for the portable file operations.

Platform compatibility

The portable path edits document files, whether or not they are open in an Office application. It does not control an open Office window. Only Windows native automation can operate on the active document, add PowerPoint animations, use Excel's calculation engine, or render slides through PowerPoint. This is a local stdio server, not a hosted service: its client must be able to launch the Node.js process and access the allowed files.

Verify a development checkout

These commands are for contributors and maintainers, not required to install the server:

npm run check
npm run smoke

npm run check type-checks, runs the portable integration tests, and builds dist/. npm run smoke launches the compiled server through an MCP client and creates a test deck. On Windows with desktop Microsoft Office installed, npm run test:native additionally tests native Excel, Word, and PowerPoint behavior. Do not run that native test on a machine without Office.

One-prompt workflow

For a request such as “analyze the financial workbook in this folder and create a board presentation,” an orchestrator can:

1. Call office_search_files to discover workbooks and templates.

2. Call office_inspect_file or excel_native_batch to understand data, formulas, and workbook structure.

3. Call excel_analyze_dataset for deterministic data-quality statistics and excel_query_dataset for focused filters, group-by summaries, and sorting; then reason about the business question and plan the story.

4. Call powerpoint_create_designed_presentation for a new narrative deck, powerpoint_create_presentation for a custom layout, or powerpoint_inspect_template followed by powerpoint_create_from_template to preserve a company deck's layouts.

5. If motion is requested, call powerpoint_native_batch to add object animations and slide transitions, then save and reopen to inspect the timeline.

6. Define a quality contract from the actual prompt, including required text, structure, numerical assertions, and—when editing—an optional baseline source file. Call office_quality_check; repair blocking issues.

7. Call office_prepare_review to render every slide or export a Word/Excel PDF, and inspect the result. For a long deck, request slides beyond the inline preview with office_get_review_image.

8. Visually critique alignment, overflow, hierarchy, and chart readability; apply corrections and rerun the check and render. PNG renders cannot demonstrate motion.

9. Call office_finalize with honest pass/fail notes for every slide, sheet, or document and every prompt criterion. It verifies the draft, contract, baseline, render evidence, and review coverage again, then copies to a separate final file without overwriting.

This is the intended separation: the AI supplies judgment; Office MCP supplies reliable handles.

Quality gate and honest limits

office_quality_check validates ZIP package relationships, checks explicit prompt assertions, and returns the draft's SHA-256 hash and review units. It can check Excel sheets, headers, exact cells, and formula errors; Word headings, tables, and image descriptions; and PowerPoint slide counts, minimum font sizes, speaker notes, and structural audit flags. A baseline.path compares an edited file to its source and blocks removed sheets, slides, or Word paragraphs by default. Contract thresholds can explicitly permit intended removal or bound changed Excel cells. office_compare_files returns the detailed semantic difference independently of finalization.

office_prepare_review creates hashed slide PNGs or a PDF and a manifest tied to the exact draft, contract, and baseline. office_finalize refuses failed machine checks, a stale or incomplete render, a changed draft, unreviewed units, failed criteria, or unaccepted warnings. The server cannot determine whether a claim is true, whether a chart tells the right story, whether a design is beautiful, or whether a reviewer genuinely inspected the output. The orchestrator must use the visual evidence and source data honestly; don't mark a criterion passed if it was not checked. Native rendering and PDF export need installed Office or LibreOffice, and PowerPoint slide PNG review specifically needs desktop PowerPoint on Windows.

Quiet background generation

Portable PPTX creation edits files directly and never opens PowerPoint. Native file-based PowerPoint operations now create or open presentations with hidden windows by default, including rendering, animation edits, and PDF export. They do not repeatedly bring a deck to the foreground.

PowerPoint automation uses a shared application instance on Windows. To avoid altering or closing a presentation the user is actively working in, the server refuses file-based native work while PowerPoint is already running. The agent should continue with portable creation and defer native rendering or animation work until PowerPoint is closed. target.active: true explicitly opts into the running session, and target.visible: true requests a visible window; neither should be used without the user's consent. Native rendering does not expose an active-session override.

Improving presentation quality

powerpoint_create_designed_presentation provides five widescreen compositions (cover, imageText, statement, comparison, panorama) and two visual styles (editorial, cinematic). panorama pairs a wide scene with an editable title and supporting copy; comparison accepts an optional takeaway to state the conclusion. It uses readable typography and crops supplied images to their frames. Supply relevant, distinct image assets when they help the story; the tool does not generate images or invent content. The lower-level PowerPoint tool remains available for charts, tables, and exact placement. Its image elements support fit: "cover", "contain", or "stretch".

The optional companion Codex skill lives at skills/office-presentation-quality/SKILL.md. Install that folder into your Codex skills directory to guide the agent through planning, render review, and revision. This skill improves the workflow; it cannot guarantee visual taste or replace a good reference deck. To use the updated server and skill in an existing Codex session, restart that session after rebuilding dist/.

powerpoint_audit_presentation works directly on any PPTX without opening Office. It reports off-slide objects, small explicitly sized text, unusually dense slides, pictures without meaningful alt text, low contrast where both colors are explicit solids, overlapping text boxes, empty slides, and grouped objects it cannot measure reliably. These are review flags, not proof of poor design. The creation tools accept image alt text (altText for custom images, imageAltText for designed layouts); without it, they use a reviewable placeholder rather than leaking a local image path into the deck.

Reusing a PowerPoint template

powerpoint_inspect_template opens an existing .pptx invisibly through desktop PowerPoint and reports its designs, custom layouts, placeholder indexes, and slide shape names. powerpoint_create_from_template can then add slides from those layouts or duplicate existing slides, fill placeholders or named text shapes, add text boxes, and save a separate .pptx. It keeps the source deck untouched and removes its original slides from the output unless keepTemplateSlides is true. Coordinates for new native text boxes are points. This requires Windows desktop PowerPoint and is subject to the quiet-background rule above; it does not import .potx files or offer arbitrary master editing yet.

Word structure and Excel analysis

word_create_document accepts either the original blocks array or a sections array with separate page size/orientation, margins, headers, footers, and page numbers. Blocks can include an updateable toc, a cited_paragraph referring to user-supplied sources, a bibliography, images with required alt text or an explicit decorative flag, hyperlinks, page breaks, and footnotes. Word fills the TOC entries when it updates the field. Citations are formatted document text, not entries in Word's built-in citation manager. Native Word batches can apply styles, insert sections, generate or refresh TOCs, and add comments to an existing document.

excel_analyze_dataset profiles a sheet or selected range for missing and duplicate rows, column types, descriptive numeric statistics, IQR outliers, top text values, dates, formula/error counts, and strongest Pearson correlations. It analyzes at most 50,000 rows and 100 columns per call. It does not clean the data, infer causation, run statistical tests, or calculate uncached formulas; use native Excel recalculation first when formula results matter.

excel_query_dataset reads up to 50,000 rows and 100 columns, applies typed filters, optionally groups and aggregates (count, countDistinct, sum, average, min, max), sorts, and returns at most 1,000 rows. It never writes back. Native Excel batches can define names, add conditional formatting, and set data validation.

Animations and transitions

On Windows with installed desktop PowerPoint, powerpoint_native_batch can apply object entrance (appear, fade, fly, wipe, zoom), emphasis (spin, growShrink), and exit (fade, fly, wipe, zoom) effects. Triggers are onClick, withPrevious, and afterPrevious; duration and delay use seconds. Call list_shapes to get a shape's name or 1-based index before add_animation. list_animations, update_animation, move_animation, delete_animation, and clear_animations support timeline inspection and revision, including repeat and reverse settings. add_media embeds a local audio or video asset. set_transition supports none, cut, fade, left/right push and wipe, and zoom-in, with optional timed advance. Include a save operation and reopen the result to verify persistence.

This is an expanding, validated Office capability set, not a wrapper around every Office command. Arbitrary COM execution is intentionally not exposed. Animation playback itself is not captured by the static PNG renderer.

Other platforms and clients

The quick start is the shortest route for Windows. The same built server works with any local stdio MCP client that can launch Node.js. Client configuration is separate: adding Office MCP to Codex does not automatically add it to Claude Code.

Codex and ChatGPT desktop

The codex mcp add command in the quick start writes Codex's user configuration, which the ChatGPT desktop app, Codex CLI, and Codex IDE extension share. In ChatGPT desktop, restart after adding the server and type /mcp to inspect it. You can also add it through Settings → MCP servers → Add server → STDIO. ChatGPT web does not read local Codex configuration; this repository does not provide a hosted MCP endpoint. See OpenAI's MCP guide.

Claude Code

The quick start uses Claude Code's user scope, so the server is available in all your local projects. Run claude mcp list or use /mcp inside Claude Code to check its connection. See Claude Code's MCP setup guide.

macOS or Linux

Portable .xlsx, .docx, and .pptx tools are designed for Node.js on these platforms, but this project's native Office bridge and PowerPoint PNG rendering are Windows-only. After cloning and running npm ci and npm run build, run the following from the repository root in a Bash-compatible shell; choose one client command:

entry="$(pwd -P)/dist/index.js"
allowed="$(pwd -P)" # Change to a directory containing the documents you want to use.
codex mcp add office --env "OFFICE_MCP_ROOTS=$allowed" -- node "$entry"
# Or: claude mcp add --scope user --env "OFFICE_MCP_ROOTS=$allowed" --transport stdio office -- node "$entry"

The default example grants access only to the repository. Set allowed to an absolute documents directory if your files live elsewhere. Restart the client, check its MCP connection, and call office_capabilities.

Other local MCP clients

Configure a stdio server with node as the command, the absolute path to dist/index.js as its argument, and OFFICE_MCP_ROOTS as an environment variable. For example, adapt this JSON to your client's format (the paths shown are placeholders):

{
  "command": "node",
  "args": ["C:\\absolute\\path\\to\\office-mcp\\dist\\index.js"],
  "env": { "OFFICE_MCP_ROOTS": "C:\\allowed\\documents" }
}

Installation troubleshooting

Path security

By default, the server may only access files below its working directory. Set OFFICE_MCP_ROOTS to one or more allowed roots.

On Windows, separate multiple roots with a semicolon:

C:\Users\your-name\Documents;D:\Company Files

On macOS and Linux, separate roots with a colon. The server resolves every input and output path before use and rejects path traversal outside these roots.

PDF conversion

office_convert_to_pdf uses LibreOffice in headless mode. The server checks standard installation locations and the system PATH. For a custom installation, set:

OFFICE_MCP_SOFFICE=C:\path\to\LibreOffice\program\soffice.exe

Call office_capabilities to see whether the converter was detected.

Development

npm run dev

The process waits silently for MCP messages on standard input. Do not write logs to standard output because stdout carries the MCP protocol. Diagnostics belong on stderr.

Manual releases

This repository has no GitHub Actions workflows or Dependabot configuration. Nothing runs automatically on pushes or pull requests, and pushing a tag does not create a release or publish to npm. It is a local stdio server, not a hosted Office service.

Before making a public release manually, update package.json and the lockfile; run npm run check and npm run smoke; and, on Windows with desktop Office, run npm run test:native. Verify a fresh packaged install and audit the bundled dependencies. Then decide whether to create a GitHub Release and attach the tested package. See CONTRIBUTING.md and SECURITY.md. No npm publication is currently configured.

Project layout:

src/
  index.ts          MCP tool registration and schemas
  office.ts         Cross-format inspection and PDF conversion
  excel.ts          XLSX adapter
  word.ts           DOCX adapter
  powerpoint.ts     PPTX adapter
  paths.ts          Allowed-root enforcement
  errors.ts         Structured MCP results and errors
  native.ts         Secure Node-to-native-Office bridge
native/
  office-bridge.ps1 Excel, Word, and PowerPoint COM automation
tests/
  office.test.ts    End-to-end file tests

Important limitations

• Native active-document control currently requires Windows and installed desktop Microsoft Office. A future Office.js bridge is required for the same live control on Mac, web, and iPad.

• ExcelJS does not support every Excel feature. Re-saving complex workbooks may not preserve unsupported objects such as embedded charts or VBA projects. Prefer a separate outputPath when editing valuable files.

• Word and PowerPoint replacement can match text split across formatting runs. When a replacement crosses multiple runs, it consolidates the replacement into the first run, so mixed character formatting inside that phrase is not retained.

• PowerPoint creation is declarative. Positions and sizes use inches, matching PptxGenJS conventions.

• The designed layouts are starting points. Template reuse is available through native PowerPoint but does not import .potx, edit a master arbitrarily, or automatically judge aesthetics. Inspect renders before delivery.

• The PPTX audit cannot determine whether text actually fits, whether contrast inherited from a theme or image background is sufficient, or whether the story and aesthetics are strong. Visually inspect rendered slides.

• Object animation and slide-transition editing currently requires desktop PowerPoint on Windows. Static slide images verify visual layout, not how effects play during a slideshow.

• Background native PowerPoint work can be deferred when PowerPoint is already running. Hidden presentations avoid pop-up windows, but this is not a fully isolated headless PowerPoint service.

• Formula values are written but not calculated by Node.js. The workbook is marked for recalculation when opened in Excel.

• The server does not offer every command in Microsoft Office, nor does it act as an autonomous design model. Quality still depends on the orchestrating model, source assets, templates, and render review.

Technology

• MCP TypeScript SDK

• ExcelJS for .xlsx

• docx for document creation

• PptxGenJS for presentation creation

• JSZip for structure-preserving OOXML inspection and targeted edits

License

MIT