Office Document MCP Server

This is a sanitized version of a prototype Model Context Protocol (MCP) server providing tools to extract, convert, and generate Microsoft Office documents (Word, Excel, PowerPoint) that I developed in parallel with go-ooxml.

Since the server itself is pretty generic code and does not support enterprise features like Information Rights Management (which I will eventually tackle with a brand new implementation atop go-ooxml), I have decided to carve it out into a standalone repository to have its own CI/CD workflows and making it easier to install via uv.

The code is considered stable, so it will not be maintained other than patches/hotfixes and there is zero support or issue tracking.

Available Tools

Core-First Tool Model

For systems architecture and consulting workflows, treat the server as core-first:

Core tools

• office_help

• office_read

• office_inspect

• office_patch

• office_table

• office_template

• office_audit

• word_insert_at_anchor

Advanced tool roles

• fallback: alternate generation/mutation paths when the core flow is not enough

• diagnostic: structure discovery, template guidance, anchors, and document maps

• legacy compatibility: parity-oriented tools kept for integration compatibility

• expert/specialized: deeper SOW/track-changes utilities for narrower workflows

Unified Tools (Primary Interface)

These 9 tools auto-detect document format from file extension or provide cross-format workflow guidance:

Specialized Tools

These remain discoverable, but should usually be reached from office_help, diagnostics, or a clear recovery need rather than as the default starting point.

Word SOW Generation

These were a proof-of-concept approach fod managing and updating specific document templates - all the tools marked sow are deprecated and kept only for historical interest.

PowerPoint Slide Management

Document Conversion

Utility

Quick Examples

Workflow Discovery

# Find the best workflow for filling a consulting SOW from markdown
office_help(
  goal="fill_sow_from_markdown",
  document_type="word",
  constraints=["preserve_template_structure"],
  format="summary"
)

# Map a common consulting request onto a deterministic workflow
office_help(
  task="Patch an Excel estimate workbook safely and verify the result",
  format="detailed"
)

# Discover the safest path for a stakeholder review deck
office_help(
  goal="create_review_deck",
  document_type="powerpoint",
  format="summary"
)

Template Analysis Cache

Word template metadata is cached on disk as JSON to avoid re-scanning the same template on every analysis call.

• default cache location: .office-metadata-cache/

• override with: OFFICE_MCP_METADATA_CACHE_DIR

• invalidation uses: resolved path + file size + mtime

• current cache-backed flow: word_parse_sow_template and office_template(operation="analyze")

Reading Documents

# Read Excel as Markdown
office_read(file_path="data.xlsx", output_format="markdown")

# Read specific range
office_read(file_path="data.xlsx", scope="Sheet1!A1:D10")

# Read a single worksheet
office_read(file_path="data.xlsx", scope="Sheet1")

# Read Excel formulas instead of cached values
office_read(file_path="model.xlsx", include_formulas=True)

# Read Word document
office_read(file_path="report.docx", output_format="markdown")

Inspecting Structure

# List Excel sheets
office_inspect(file_path="data.xlsx", what="sheets")

# List Word tables
office_inspect(file_path="report.docx", what="tables")

# List PowerPoint slides
office_inspect(file_path="deck.pptx", what="slides")

# Analyze a Word template and reuse cached metadata on later runs
office_template(
  source_path="templates/sow.docx",
  destination_path="",
  operation="analyze"
)

# Discover insertion anchors before adding narrative content
word_list_anchors(file_path="report.docx", query="delivery")

# Get a compact map of a Word document
word_document_map(file_path="report.docx")

Editing Content

# Patch Excel cell
office_patch(
  file_path="data.xlsx",
  changes=[{"target": "A1", "value": "New Value"}]
)

# Patch Word placeholder
office_patch(
  file_path="report.docx",
  changes=[{"target": "<Customer>", "value": "Contoso"}]
)

# Patch PowerPoint shape
office_patch(
  file_path="deck.pptx",
  changes=[{"target": "slide:1/Title 1", "value": "New Title"}]
)

# PowerPoint soft return in a single text box
office_patch(
  file_path="deck.pptx",
  changes=[{"target": "slide:1/Title 2", "value": "Contoso{br}Project"}]
)

Mutation tools now expose a common diagnostics shape for covered Word/Excel workflows and support explicit execution modes on selected high-value paths (best_effort, safe, strict, dry_run).

• success

• status (success, partial_success, failed, skipped)

• warnings

• matched_targets

• unmatched_targets

• skipped_targets

• diagnostics

• next_tools

That makes partial success and recovery paths explicit instead of relying on generic success messages.

• best_effort: current compatibility-oriented behavior

• safe: requires a distinct output path for covered mutation flows

• strict: refuses writes when requested targets cannot all be matched cleanly

• dry_run: predicts matches and diagnostics without writing files

Table Operations

# Add row to Word table
office_table(
  file_path="report.docx",
  operation="add_row",
  table_id="staffing",
  data={"Role": "PM", "Count": "1", "Notes": "Lead"}
)

# Create table in Word
office_table(
  file_path="report.docx",
  operation="create",
  data={
    "headers": ["Phase", "Owner", "Target Date"],
    "rows": [{"Phase": "Discovery", "Owner": "PM", "Target Date": "2026-04-01"}],
    "insert_after_section": "Delivery Plan"
  }
)

# Add table to PowerPoint
office_table(
  file_path="deck.pptx",
  operation="create",
  table_id="3",
  data={
    "headers": ["Phase", "Duration"],
    "rows": [["Discovery", "2 weeks"]]
  }
)

Track Changes Workflows

# Enable Track Changes in document settings
word_enable_track_changes(file_path="draft.docx", output_path="draft-tracked.docx")

# Apply a tracked replacement
word_patch_with_track_changes(
  file_path="draft-tracked.docx",
  replacements={"Old wording": "New wording"},
  output_path="draft-review.docx"
)

# Accept tracked changes and normalize the final document
word_accept_all_changes(
  file_path="draft-review.docx",
  output_path="draft-final.docx"
)

Image Support

office_image supports raster formats (PNG, JPG/JPEG, GIF) across Word, Excel, and PowerPoint.

SVG support is currently:

Notes:

• Excel image placement is cell-anchored.

• PowerPoint image placement is centered by default and can be validated from returned position metadata.

• Recent local MCP validation covered image insertion plus position/bounds checks for Excel and PowerPoint fixture copies.

Large Markdown Inputs

# Avoid MCP argument-size limits by passing a markdown_file path
word_from_markdown(
  output_path="report.docx",
  markdown_file="inputs/large-report.md"
)

excel_from_markdown(
  output_path="budget.xlsx",
  markdown_file="inputs/budget-tables.md"
)

pptx_from_markdown(
  output_path="deck.pptx",
  markdown_file="inputs/deck.md"
)

word_create_sow_from_markdown(
  output_path="sow.docx",
  template_path="templates/Agile.docx",
  markdown_file="inputs/sow.md"
)

Auditing

# Audit for placeholders
office_audit(file_path="report.docx", checks=["placeholders"])

# Audit for completion
office_audit(file_path="report.docx", checks=["completion"])

Comment Threads and Resolution (Word)

Word stores comment text in word/comments.xml and thread/resolution metadata in word/commentsExtended.xml.

word_get_comments

word_get_comments(
  file_path="SoW.docx",
  filter="all",      # all | open | resolved | mine
  author=None,        # used with filter="mine"
  format="flat"      # flat | threaded
)

Each comment now includes:

• id

• author

• initials

• date

• text

• done (resolved state)

• is_reply

• parent_id

• para_id

When format="threaded", response includes:

• threads: grouped { root, replies[] }

• flat: full backward-compatible flat list

word_resolve_comment

word_resolve_comment(
  file_path="SoW.docx",
  comment_id="121",
  resolved=True,      # True=resolve, False=reopen
  output_path=None,
)

Notes:

• If a reply ID is supplied, the root thread is resolved/reopened.

• If commentsExtended.xml is missing, it is created and wired into the package.

• If root comments lack w14:paraId, a paraId is synthesized for stable mapping.

word_reply_to_comment

word_reply_to_comment(
  file_path="SoW.docx",
  comment_id="121",
  text="Done — updated as requested.",
  author="Rui Carmo",
  auto_resolve=True,
)

auto_resolve=True performs reply + resolve in one call.

Unified API (office_comment)

office_comment supports Word thread workflows directly:

office_comment(file_path="SoW.docx", operation="get", format="threaded")
office_comment(file_path="SoW.docx", operation="get", filter="open")
office_comment(file_path="SoW.docx", operation="resolve", target="121")
office_comment(file_path="SoW.docx", operation="reopen", target="121")

Supported operations:

• Word: add, get, reply, resolve, reopen, delete

• Excel: add, get, delete (reply/resolve/reopen return clear unsupported errors)

• PowerPoint: add, get, delete (reply/resolve/reopen return clear unsupported errors)

End-to-end round-trip tests

Fixture-based tests cover:

• mixed open/resolved states

• resolve/reopen toggling

• reply-to-root resolution behaviour

• legacy commentsIds.xml fallback

• missing commentsExtended.xml creation

• threaded retrieval + filtering

• output-path round trips

Primary test files:

• tests/test_word_comment_resolution.py

• tests/test_word_comment_roundtrip_fixture.py

• tests/test_word_comment_replies.py

Word Review Workflow

The recommended workflow for reviewing documents is this:

1. office_help(goal="fill_sow_from_markdown") → Choose the workflow and recovery path first
2. office_template(operation="copy")          → Create working document from template
3. office_template(operation="analyze")       → Understand what to preserve vs fill
4. office_inspect(what="tables")              → Get EXACT column names for all tables
5. word_generate_sow                           → Fill placeholders and tables with data
6. office_patch(operation="section")          → Add prose to Introduction, Business Context
7. office_table(operation="insert_row")       → Add engagement-specific rows to tables
8. office_patch(operation="fix_split")        → Replace any remaining split placeholders
9. office_comment(operation="add")            → Add review comments for stakeholders
10. word_cleanup_sow                           → Remove template guidance (tracked)
11. office_audit(checks=["completion"])       → Verify completion score ≥ 80%

Quality Bar: All review tools preserve document structure by editing templates rather than creating new documents from scratch. All changes are tracked for stakeholder review.

Setup

Install from repository (recommended)

Using uv:

uv pip install "git+https://github.com/rcarmo/python-office-mcp-server.git"

Using pip:

pip install "git+https://github.com/rcarmo/python-office-mcp-server.git"

This installs the office-mcp-server command. Requires Python ≥3.10 (tested with 3.12).

Install from local clone

git clone https://github.com/rcarmo/python-office-mcp-server.git
cd python-office-mcp-server
uv pip install .
# or: pip install .
# or for development: pip install -e .

Run without installing

git clone https://github.com/rcarmo/python-office-mcp-server.git
cd python-office-mcp-server
pip install -r requirements.txt
python office_server.py

MCP client configuration

VS Code (.vscode/mcp.json):

{
  "servers": {
    "office": {
      "command": "office-mcp-server"
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "office": {
      "command": "office-mcp-server"
    }
  }
}

mcp-cli (mcp_servers.json):

{
  "mcpServers": {
    "office": {
      "command": "office-mcp-server"
    }
  }
}

If using uvx or bunx instead of a pre-installed binary:

{
  "command": "uvx",
  "args": ["--from", "git+https://github.com/rcarmo/python-office-mcp-server.git", "office-mcp-server"]
}

Tool Activation Note

Some MCP clients can start with subsets of tools disabled by policy/session settings. If a call returns a disabled-tool error, enable the corresponding MCP tools in the client first, then retry. This enablement behavior is controlled by the MCP client/host, not by this server.

VS Code (Automatic)

The server can be set to be auto-discovered from .vscode/mcp.json. That is left as an exercise to the reader, but to verify: Open Command Palette → MCP: List Servers → confirm officeServer is listed.

GitHub Copilot CLI

Add the server to your Copilot CLI configuration:

# Open config file
code ~/.config/github-copilot/config.json

# Add this to the mcpServers section:
{
  "mcpServers": {
    "officeServer": {
      "command": "python",
      "args": ["/path/to/.github/mcp/office_server.py"]
    }
  }
}

Running Manually

cd .github/mcp
pip install -r requirements.txt
python office_server.py

Windows Single-File Distribution

Build a standalone .exe using PyInstaller.

Build on Windows

cd .github/mcp
python -m pip install -r requirements.txt
python -m pip install -r requirements-build.txt
python build_windows_onefile.py --clean

Output artifact:

• dist/office-mcp-server.exe

Custom output name

python build_windows_onefile.py --name office-server-prod

Run executable

dist\office-mcp-server.exe

Use the generated executable in MCP client configuration by pointing command to the .exe path.

Dependencies

• python-docx — Word document handling

• openpyxl — Excel workbook handling

• python-pptx — PowerPoint presentation handling

• aioumcp — Async MCP server framework

• pyinstaller — Build-time dependency for one-file Windows executable

Architecture

The server dynamically loads tool modules from tools/:

• office_unified_tools.py — Unified interface (7 tools)

• word_tools.py — Word conversion tools

• word_advanced_tools.py — SOW-specific tools

• excel_tools.py — Excel conversion tools

• excel_advanced_tools.py — Excel advanced operations (internal)

• pptx_tools.py — PowerPoint conversion tools

• pptx_advanced_tools.py — Slide management tools

Tools are discovered automatically by class name pattern (*Tools).