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

Unified Tools (Primary Interface)

These 8 tools auto-detect document format from file extension:

Tool	Description
office_read	Read content from Word/Excel/PowerPoint as JSON or Markdown
office_inspect	Get document structure (sheets, slides, sections, tables, comments)
office_patch	Edit cells, shapes, sections, or replace placeholders
office_comment	Add or get comments from any document type
office_table	Table operations: add rows, create tables, add bullets
office_template	Copy templates or analyze template structure
office_audit	Audit for placeholders, completion, or tracking status
office_image	Insert images into Word, Excel, or PowerPoint documents

Specialized Tools

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.

Tool	Description
word_generate_sow	Fill SOW template with structured data
word_cleanup_sow	Remove template artifacts and guidance (tracked)
word_get_section_guidance	Extract template instructions from a section
word_parse_sow_template	Analyze SOW template structure
word_create_sow_from_markdown	Create SOW from Markdown content
word_extract_sow_structure	Extract structured data from existing SOW
word_enable_track_changes	Enable Word's track changes mode
word_patch_with_track_changes	Replace text with revision marks

PowerPoint Slide Management

Tool	Description
pptx_add_slide	Add new slide with specified layout
pptx_delete_slide	Remove a slide
pptx_duplicate_slide	Copy a slide
pptx_reorder_slides	Change slide order
pptx_hide_slide	Hide/unhide a slide
pptx_set_notes	Set speaker notes
pptx_recommend_layout	Get best layout for content type
pptx_log_changes	Add change log slide

Document Conversion

Tool	Description
word_from_markdown	Create Word document from Markdown
excel_from_markdown	Create Excel workbook from Markdown tables
pptx_from_markdown	Create PowerPoint from Markdown slides

Utility

Tool	Description
restart_server	Hot-reload the server after code changes
list_supported_formats	Show available document formats

Quick Examples

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 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")

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"}]
)

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"}
)

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

Auditing

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

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

Word Review Workflow

The recommended workflow for reviewing documents is this:

1. office_template(operation="copy")      → Create working document from template
2. office_template(operation="analyze")   → Understand what to preserve vs fill
3. office_inspect(what="tables")          → Get EXACT column names for all tables
4. word_generate_sow                      → Fill placeholders and tables with data
5. office_patch(operation="section")      → Add prose to Introduction, Business Context
6. office_table(operation="insert_row")   → Add engagement-specific rows to tables
7. office_patch(operation="fix_split")    → Replace any remaining split placeholders
8. office_comment(operation="add")        → Add review comments for stakeholders
9. word_cleanup_sow                       → Remove template guidance (tracked)
10. 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).