Office MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Office MCP Review the Q3 sales Excel file and highlight the top 10 rows"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Office MCP
Office MCP is a Windows-native Model Context Protocol (MCP) server providing high-fidelity automation, AST inspection, and transactional mutation of Microsoft Office documents (Excel, Word, and PowerPoint).
Built on top of FastMCP, Office MCP combines native Windows COM automation (via pywin32 with Single-Threaded Apartment isolation) with pure-Python fallbacks (openpyxl, python-docx, python-pptx), backed by an airtight Safety Engine featuring path sandboxing, in-memory concurrency locks, automatic SHA-256 pre-mutation snapshots, SQLite WAL audit logging, and post-mutation invariant verifiers.
Table of Contents
Related MCP server: docforge-mcp
Architecture Overview
flowchart TD
Client["LLM / MCP Client<br/>(Claude, Antigravity, Cursor)"] -->|JSON-RPC| Server["FastMCP Server<br/>(office_mcp.server)"]
subgraph SafetyEngine ["Safety & Concurrency Engine"]
Sandbox["Path Sandbox<br/>(OFFICE_MCP_ALLOWED_ROOTS)"]
LockMgr["DocumentLockManager<br/>(Exclusive in-memory write locks)"]
SnapMgr["SnapshotManager<br/>(.office_snapshots + SHA-256)"]
Audit["AuditLogger<br/>(SQLite WAL: office_audit.db)"]
end
subgraph ExecutionLayer ["Transactional Execution Pipeline"]
Executor["ChangeSet Executor"]
Verifier["Verification Engine<br/>(AST, Formula Errors, Visual PNG)"]
end
subgraph DriverLayer ["Dual-Tier Office Drivers"]
Worker["STA Worker Registry<br/>(Dedicated Thread + pythoncom Pump)"]
COM["Windows COM Automation<br/>(Excel, Word, PowerPoint .Application)"]
Fallback["Pure-Python Fallbacks<br/>(openpyxl, python-docx, python-pptx)"]
end
Server --> Sandbox
Sandbox --> LockMgr
LockMgr --> SnapMgr
SnapMgr --> Executor
Executor --> DriverLayer
DriverLayer --> Worker
Worker --> COM
Worker -.->|Non-Windows| Fallback
Executor --> Verifier
Verifier -->|Pass| Commit["Commit Document & Release Lock"]
Verifier -->|Fail| Rollback["Auto-Rollback to .bak Snapshot"]
Commit --> Audit
Rollback --> AuditKey Capabilities & Safety Guarantees
Inspect First, Minimize Mutations, Verify Everything: Full document hierarchy and metadata inspection prior to applying modifications.
STA COM Isolation: Windows COM calls execute in dedicated Single-Threaded Apartment background threads with active message pumps (
pythoncom.PumpWaitingMessages()) and task timeouts to avoid modal dialog deadlocks.Canonical Filesystem Sandboxing: Operations outside
OFFICE_MCP_ALLOWED_ROOTSare immediately rejected (SecuritySandboxError).Pre-Mutation Snapshot & Auto-Rollback: Byte-exact
.baksnapshots are generated before any write. Invariant failures (e.g.,#REF!,#DIV/0!, corrupted AST, missing elements) trigger an automatic, immediate rollback.High-Performance 2D SAFEARRAY Marshaling: Bulk matrix data assignment in Excel COM runs orders of magnitude faster than individual cell writes.
Visual Slide Verification: PowerPoint slides can be exported to PNG at custom resolutions and validated against bounding box collisions.
SQLite WAL Audit Trail: All reads, writes, snapshots, and rollbacks are recorded with execution metrics in
office_audit.db.
Prerequisites & Installation
System Requirements
Operating System: Windows 10/11 or Windows Server (for native COM automation). Cross-platform environments will utilize fallback drivers.
Microsoft Office: Office 2016, 2019, 2021, or Microsoft 365 desktop apps installed (for COM drivers).
Python: Version
3.10or higher.
Installation
Clone the repository and install the package using pip or uv:
# Clone repository
git clone https://github.com/your-org/office-mcp.git
cd office-mcp
# Create and activate virtual environment
python -m venv .venv
.venv\Scripts\activate
# Install package in editable mode
pip install -e .
# (Optional) Install development dependencies
pip install -e ".[dev]"Configuration
Office MCP is configured through environment variables or a .env file in the root directory:
Environment Variable | Default Value | Description |
|
| JSON array or comma-separated list of allowed absolute paths for file operations. |
|
| Directory name for pre-mutation |
|
| Path to SQLite audit database (WAL mode enabled). |
|
| Timeout in seconds for individual COM task execution. |
|
| Timeout in seconds for acquiring an exclusive document lock. |
|
| Maximum number of snapshots preserved per document directory. |
|
| Logging level ( |
|
| Security flag controlling whether VBA macros are allowed to run. |
Client Integration
Claude Desktop
Add the server to your claude_desktop_config.json:
{
"mcpServers": {
"office-mcp": {
"command": "python",
"args": ["-m", "office_mcp.server"],
"env": {
"OFFICE_MCP_ALLOWED_ROOTS": "[\"C:\\\\path\\\\to\\\\documents\", \"C:\\\\path\\\\to\\\\workspace\"]",
"OFFICE_MCP_LOG_LEVEL": "INFO"
}
}
}
}Antigravity / Gemini CLI
In your project configuration or user settings (mcp_config.json):
{
"mcpServers": {
"office-mcp": {
"command": "python",
"args": ["-m", "office_mcp.server"],
"cwd": "C:/path/to/office-mcp",
"env": {
"OFFICE_MCP_ALLOWED_ROOTS": "[\"C:/path/to/office-mcp\"]"
}
}
}
}VS Code / Cursor (.mcp.json)
{
"servers": {
"office-mcp": {
"type": "stdio",
"command": "${workspaceFolder}/.venv/Scripts/python.exe",
"args": ["-m", "office_mcp.server"]
}
}
}MCP Tools Reference
The server exposes 19 specialized tools categorized by application and function:
Excel Tools
Tool Name | Parameters | Description |
|
| Opens an Excel workbook within allowed roots and returns sheet, table, and range metadata. |
|
| Creates a new workbook (.xlsx) with optional custom sheet names. |
|
| Returns AST metadata: used ranges, tables ( |
|
| Reads a 2D matrix of values and formulas from an Excel range (e.g. |
|
| Applies an atomic batch of operations (values, formulas, formatting, tables, charts) with post-validation and automatic rollback. |
|
| Exports workbook or active sheet directly to high-fidelity PDF. |
Word Tools
Tool Name | Parameters | Description |
|
| Opens a Word document (.docx) and extracts its AST metadata. |
|
| Creates a new document with an optional Heading 1 title. |
|
| Extracts full document AST (headings, paragraphs, styles, word/character count, and tables). |
|
| Applies atomic operations (headings, paragraphs, bullet lists, tables, cell merges, styles) with structural invariant verification. |
|
| Exports a Word document directly to PDF format. |
PowerPoint Tools
Tool Name | Parameters | Description |
|
| Opens a presentation (.pptx) and returns slide metadata. |
|
| Creates a new presentation with 16:9 widescreen or 4:3 standard aspect ratio. |
|
| Inspects slides, shape geometries, text frames, positions, and layout types. |
|
| Applies slide creations, textbox additions, shape updates, and image insertions with bounding box checks. |
|
| Renders a specific slide to a PNG image for visual inspection. |
|
| Exports the full presentation to PDF. |
General & Safety Tools
Tool Name | Parameters | Description |
|
| Manually restores a document to its pre-mutation |
|
| Queries recorded audit logs from |
MCP Resources & Prompts
Resources
office://audit-logs: Live JSON stream of recent document operations and status codes.office://settings: Current runtime configuration and canonical allowed root paths.
Workflow Prompts
spreadsheet-audit: Pre-configured guided prompt for scanning Excel workbooks for formula errors, broken references, and unformatted data ranges.report-generation: Guided workflow for assembling professional Word documents with structured tables, executive summaries, and heading hierarchies.presentation-builder: Guided workflow for generating polished PowerPoint decks adhering to widescreen aspect ratios and visual typography rules.
Transactional ChangeSet Protocol
ChangeSets represent atomic units of work. If any operation fails or any invariant is violated during post-mutation verification, the entire batch is rolled back to the pre-mutation snapshot.
Excel ChangeSet Example
{
"document_id": "C:/path/to/documents/Financials.xlsx",
"intent": "Update Q4 Revenue and format summary table",
"operations": [
{
"op_type": "set_range",
"target": "A1:C3",
"params": {
"sheet": "Summary",
"values": [
["Quarter", "Revenue", "Expenses"],
["Q3", 150000, 90000],
["Q4", 220000, 110000]
]
}
},
{
"op_type": "set_formula",
"target": "B4",
"params": {
"sheet": "Summary",
"formula": "=SUM(B2:B3)"
}
},
{
"op_type": "format_range",
"target": "A1:C1",
"params": {
"sheet": "Summary",
"bold": true,
"bg_color_rgb": "#1F4E78",
"color_rgb": "#FFFFFF"
}
},
{
"op_type": "create_table",
"target": "SummaryTable",
"params": {
"sheet": "Summary",
"range_address": "A1:C3",
"style": "TableStyleMedium9"
}
}
],
"expected_invariants": [
"no_formula_errors"
],
"risk_level": "low",
"dry_run": false
}Word ChangeSet Example
{
"document_id": "C:/path/to/documents/Quarterly_Report.docx",
"intent": "Add Executive Summary and Financial Metrics Table",
"operations": [
{
"op_type": "add_heading",
"target": "Executive Summary",
"params": { "level": 1 }
},
{
"op_type": "add_paragraph",
"target": "During Q4, overall performance exceeded targets across all key business units.",
"params": { "font_size_pt": 11 }
},
{
"op_type": "insert_table",
"target": "",
"params": {
"rows": 3,
"cols": 3,
"headers": ["Department", "Budget", "Actual"],
"data": [
["Engineering", "$500,000", "$480,000"],
["Marketing", "$200,000", "$210,000"]
],
"style": "Table Grid"
}
}
],
"expected_invariants": [
{
"invariant_type": "min_paragraphs",
"expected_value": 2
}
],
"risk_level": "low"
}PowerPoint ChangeSet Example
{
"document_id": "C:/path/to/documents/PitchDeck.pptx",
"intent": "Add Title Slide and KPI Callout Shapes",
"operations": [
{
"op_type": "add_slide",
"target": "",
"params": {
"layout_num": 12,
"title": "Q4 Performance Overview"
}
},
{
"op_type": "add_textbox",
"target": "Strategic Growth & Milestones",
"params": {
"slide_index": 1,
"left": 100,
"top": 120,
"width": 800,
"height": 60,
"font_size": 32,
"bold": true,
"color_rgb": "#111827"
}
},
{
"op_type": "add_shape",
"target": "rounded_rectangle",
"params": {
"slide_index": 1,
"left": 100,
"top": 220,
"width": 300,
"height": 160,
"fill_color": "#2563EB",
"text": "+45% YoY Growth"
}
}
],
"expected_invariants": [
{
"invariant_type": "min_slide_count",
"expected_value": 1
}
],
"risk_level": "medium"
}Development & Testing
Office MCP includes an extensive unit and integration test suite using pytest:
# Run full test suite
pytest
# Run tests with verbose output
pytest -v
# Run only Excel driver tests
pytest tests/test_excel.py
# Run only safety engine tests
pytest tests/test_safety.pyCode formatting and static type checking are enforced via ruff and mypy:
# Format and lint code
ruff check src tests
ruff format src tests
# Static type verification
mypy srcTroubleshooting & COM Error Handling
Office MCP translates low-level Windows COM HRESULT codes into clear, actionable domain exceptions:
COM HRESULT | Hex Code | Domain Exception | Description & Recovery |
|
|
| An internal Office application error occurred. Check parameters. |
|
|
| Office application is busy displaying a modal dialog. Closed via watchdog. |
|
|
| Office application is handling user interaction. Retried automatically. |
|
|
| COM object accessed across apartment boundaries without marshaling. STA worker ensures thread affinity. |
|
|
| The requested document path does not exist. |
|
|
| Document is locked by another process or instance. |
|
|
| Unspecified COM failure. The engine performs an automatic snapshot restore. |
Diagnostic Tips
Orphaned Office Processes: If Excel, Word, or PowerPoint remain hanging in Task Manager, Office MCP's
ProcessManagerterminates registered instances on shutdown. You can also force-terminate via PowerShell:Stop-Process -Name EXCEL, WINWORD, POWERPNT -Force -ErrorAction SilentlyContinueAudit Inspection: Inspect
office_audit.dbusing theoffice_query_audit_logstool or any SQLite viewer to review error stack traces and rollback history.
Available Tools
19 toolsexcel_apply_changesetA
Apply an atomic ChangeSet to an Excel workbook with formula verification and rollback
Inputs: changeset (required). Returns: object
excel_create_workbookA
Create a new Excel workbook with custom sheets
Inputs: path (required), sheets. Returns: object
excel_export_pdfB
Export an Excel workbook to PDF format
Inputs: path (required), target_pdf (required). Returns: object
excel_inspectB
Inspect structural metadata of an Excel workbook
Inputs: path (required), sheet_name. Returns: object
excel_openB
Open an existing Excel workbook and inspect metadata
Inputs: path (required), read_only. Returns: object
excel_read_rangeA
Read a 2D matrix of values and formulas from an Excel range
Inputs: path (required), range_address (required), sheet_name. Returns: object
office_query_audit_logsA
Query recent execution logs from the SQLite audit database
Inputs: limit, status, app_type, canonical_path. Returns: object
office_rollback_documentB
Restore a document to its pre-mutation snapshot backup
Inputs: path (required), snapshot_id. Returns: object
powerpoint_apply_changesetA
Apply an atomic ChangeSet to a PowerPoint presentation with visual bounds checking and rollback
Inputs: changeset (required). Returns: object
powerpoint_create_presentationA
Create a new PowerPoint presentation with aspect ratio (16:9 or 4:3)
Inputs: path (required), aspect_ratio. Returns: object
powerpoint_export_pdfA
Export a PowerPoint presentation to PDF format
Inputs: path (required), target_pdf (required). Returns: object
powerpoint_inspectA
Inspect slides, layout names, shapes, and text frames in a PowerPoint presentation
Inputs: path (required). Returns: object
powerpoint_openB
Open an existing PowerPoint presentation and inspect metadata
Inputs: path (required), read_only. Returns: object
powerpoint_render_slideA
Render a slide to a PNG image for visual inspection and multimodal verification
Inputs: path (required), width, height, target_png, +1 more. Returns: object
word_apply_changesetA
Apply an atomic ChangeSet to a Word document with structural verification and rollback
Inputs: changeset (required). Returns: object
word_create_documentA
Create a new Word document with optional heading title
Inputs: path (required), title. Returns: object
word_export_pdfB
Export a Word document to PDF format
Inputs: path (required), target_pdf (required). Returns: object
word_inspectB
Inspect structural hierarchy and AST of a Word document
Inputs: path (required). Returns: object
word_openB
Open an existing Word document and inspect AST metadata
Inputs: path (required), read_only. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 19 tools
Format prefixes make tool groups clear, but within each format `open` and `inspect` heavily overlap: both return metadata or structural information. An agent could easily select the wrong one when trying to examine a document. Other tools like read_range, apply_changeset, and export_pdf are more distinct.
All tools follow a consistent `{scope}_{verb}_{object}` snake_case pattern, such as excel_create_workbook and powerpoint_render_slide. The cross-cutting office_* tools are also predictable and fit the convention. Naming is highly consistent across all 19 tools.
19 tools is slightly above the ideal sweet spot, but the count is justified by three distinct document formats and shared cross-cutting capabilities. Each format has a coherent set of create/open/inspect/apply/export tools, plus PowerPoint rendering, so nothing feels extraneous.
The tool surface covers the core document lifecycle: create, open, inspect/read, mutate via changesets, rollback, export, and audit. The main gaps are minor, such as no explicit save-as or search tool, but agents can work around these with inspect and changeset operations. Overall, the domain is well covered without severe dead ends.
Maintenance
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Online office suite for AI agents: edit docs, sheets, slides and PDFs in browser or via MCP.
Create and manage documents, spreadsheets, and presentations from your AI assistant.
Build and run agents and automations across hundreds of apps using natural language.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAI-powered Office automation server that enables creating, editing, and processing Word, Excel, and PowerPoint documents through natural language instructions using Python-based libraries.1MIT
- AlicenseBqualityCmaintenanceEnables complete Office document lifecycle management for AI agents, including creation, editing, conversion, and templating of DOCX, XLSX, PPTX, PDF, and EML files.4089 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceGenerates PowerPoint, Excel, Word, and Markdown files from natural language requests and reviews Word documents with AI comments.84MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, edit, format, and analyze Microsoft Office documents (Excel, Word, PPT, PDF) using natural language, with features like table replication and automated styling.2MIT