Microsoft 365 for Mac MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Microsoft 365 for Mac MCP
Dual-mode (file-level + live AppleScript) MCP server for Microsoft Excel, Word, and PowerPoint — verified on macOS 27.x & Microsoft Office 16.x (m365-mac-mcp).
A Model Context Protocol (MCP) server (m365-mac-mcp) that enables AI assistants to create, inspect, format, audit, and automate Microsoft Office documents (Excel, Word, and PowerPoint) on macOS.
This server combines fast file-level manipulation (openpyxl, python-docx, python-pptx) with hardened live macOS Office automation via AppleScript (osascript) for real-time Excel formula recalculation, live Word editing, and seamless view-preserving sync with open workbooks.
Author: Sterling Jimenez, Ph.D. (stejimenez@gmail.com)
This is a personal open-source project and is not an official Microsoft MCP Server.
Highlights & Architecture
Dual-Mode Engine (File-Level + Live App):
File-level tools (
openpyxl,python-docx,python-pptx) handle bulk reads/writes, multi-sheet batch formatting, charts, Excel tables, data validation, named styles, formula auditing, and rich.docxtable/paragraph styling without blocking the UI.Live-app tools (
excel_live_*,word_live_*) drive Microsoft Excel and Microsoft Word directly via serialized, timeout-guarded AppleScript (osascript -+argv) for real Excel formula evaluation, live edits, custom views, invalid-data circles, and PDF/RTF/TXT export.
Token-Efficient by Design (Zero Loss of Exactitude):
Compact JSON wire responses (
separators=(",", ":"),structured_output=False) cut 2D spreadsheet response payloads by 46%–74% with zero data loss.Sparse A1 formula maps (
{"D2": "=(C2/B2)-1", ...}) ininspect_workbook,excel_live_read_range, andexcel_live_batch_read_rangeseliminate duplicated 2D matrices while making formula coordinates explicit.Deduplicated Word reads (
read_document): Omits duplicatefull_text(opt-in viainclude_full_text=True), duplicateheadings, default"style": "Normal", and empty metadata/tables — cutting Word read tokens by ~40%–50% with zero data loss.Compacted MCP tool schemas strip Pydantic
"title", redundant"default": null, and verbose nullableanyOfwrappers (-35% per-turn schema overhead) while preserving full runtime validation.Trimmed trailing blanks & omitted empty boilerplate keep responses tight without hiding non-empty data or truncation flags.
Live Excel Auto-Sync (
OFFICE_MCP_LIVE_SYNC=auto): Whensave_workbookwrites to a file already open in Excel with no unsaved edits, it automatically captures the window bounds, active sheet, zoom, scroll position, and selection, reloads the saved file in Excel, and restores your exact view. If you have unsaved manual edits in Excel, it refuses to overwrite so your work is never lost.Composable Tool Profiles (
OFFICE_MCP_PROFILE): Trim the exposed toolset (e.g.,excel,compact,excel,word,word,powerpoint) to cut schema token overhead by up to 60%+ on local LLMs (LM Studio / Bionic).Hardened for Modern macOS & Office for Mac:
Verified on macOS (Apple Silicon) with Microsoft Excel 16.115 and Microsoft Word 16.115.1.
Per-event-loop
asyncio.Lockserialization aroundosascriptcalls prevents parallel AppleEvent races.Automatic quoting of spaced sheet names in formulas (e.g.,
=Cash Flow!F15→='Cash Flow'!F15) and pre-write validation prevents Excel modal dialogs and strayxl/externalLinks.Compatible with both MCP SDK v2 and MCP SDK v1, with strict
stderr-only logging sostdioJSON-RPC streams are never polluted.
Related MCP server: Excel MCP Server
Features
Excel (File-Level & Live App)
Workbook & Sheet Management: Create, open, close, save (
.xlsx,.xlsm,.csv,.pdf), add/rename/delete/activate worksheets, and one-callinspect_workbook.Bulk & Batch Operations: Read/write cells and ranges (with
include_formulas/evaluate_formulasaliases),batch_write_ranges,batch_format_workbook,excel_live_batch_read_ranges, andexcel_live_batch_write_cells.Financial-Model Styling & Formatting:
format_range,format_worksheet,batch_format_workbook, andset_column_widths(explicit widths or auto-fit with padding).Supports comma-separated multi-ranges (
"B2:F3, B6:F7"), merged font/alignment/border preservation, per-side borders (thin,medium,thick,double,dashed,dotted,none), andauto_color_financial_model=True(blue inputs, black same-sheet formulas, green cross-sheet links).16 built-in named cell style presets (
Normal,Good,Bad,Neutral,Input,Calculation,Check Cell,Linked Cell,Note,Output,Warning Text,Title,Heading 1–Heading 4,Total) vialist_cell_styles/apply_cell_style.
Tables, Charts & Data Validation:
Native Excel Tables (
add_excel_table,update_excel_table_style,excel_live_update_table_style) withTableStyleLight*/Medium*/Dark*and banded row/column toggles.Charts (
create_chart: bar, column, line, pie).Data validation rules (
add_data_validation,list_data_validations,clear_data_validations) plus live invalid-data circles (excel_live_circle_invalid).
Formula Auditing & Live Recalculation:
One-call
audit_workbook_formulaschecks for#REF!,#NAME?,#VALUE!,#DIV/0!,#N/A, external links, and broken sheet references.Live Excel reads use bulk single-AppleEvent matrix extraction (10–50× faster and reliable on vertical
N×1ranges) with live recalculation (recalculate=True).Live Custom Views (
excel_live_custom_views) and capability inspection (excel_view_capabilities).
Word (File-Level & Live App)
Document Operations: Create, open (including legacy
.docconversion), close, read paragraphs/tables, set document properties, search & replace, and export to.docx,.pdf,.rtf, or.txt.Rich
.docxStyling:Full formatting on
add_heading,add_paragraph,insert_paragraph,add_list,format_paragraph(fonts, colors, alignment, line spacing,keep_with_next, indents, shading/background, bottom borders).Full table styling on
add_table,format_table, andupdate_table_cell(column widths in inches withautofit=False, header/body styles, alternating row shading, XML borders, cell padding in pt,repeat_header/w:tblHeader, table & per-column alignment).
Live Word Automation: List open documents (with multi-tier cascade hardened for Word 16.115.1), open, read, write/append, search & replace, save/export, and close directly in Microsoft Word.
PowerPoint
Create presentations with custom titles and themes
Add slides with standard layouts
Insert text, images, and speaker notes
Save presentations in multiple formats
Prerequisites
System Requirements
macOS 10.15 or later (recommended: Apple Silicon macOS 27.x)
Python 3.10+ (recommended: Python 3.12 in a local
.venv)Microsoft 365 / Office for Mac (Excel, Word, and/or PowerPoint)
Recommended & Tested Reference Setup
This server was developed, benchmarked, and end-to-end verified on the following 100% local Apple Silicon setup:
Component | Verified Configuration |
Hardware | Mac mini (Apple M4 Pro, |
Operating System | macOS 27.2.1 (Build |
Microsoft 365 for Mac | Excel |
MCP Client & Runtime | Bionic |
Local Inference Model |
|
Python Environment | Python |
Recommended MCP Env |
|
Installation
Clone the repository
git clone https://github.com/stejimenez/m365-mac-mcp.git cd m365-mac-mcpCreate a virtual environment and install dependencies
python3 -m venv .venv .venv/bin/pip install -r requirements.txtrequirements.txtinstalls:mcp>=1.2.0python-docx>=1.1.0openpyxl>=3.1.2python-pptx>=1.0.0aiofiles>=23.2.1,typing-extensions>=4.12.0pytest>=8.0.0,pytest-asyncio>=0.23.0
Grant macOS Automation permissions
Live Office tools use AppleScript to control Office apps:
Open System Settings → Privacy & Security → Automation
Locate your host application (Terminal, iTerm2, VS Code, Bionic, Claude Desktop, etc.)
Enable:
Microsoft Excel
Microsoft Word
Microsoft PowerPoint
Click OK if macOS prompts on first run.
Configuration
Environment Variables
Variable | Default | Description |
|
| Comma-separated, case-insensitive tool profile filter (see table below). |
|
|
|
|
| Logging verbosity ( |
|
| Timeout in seconds for each |
|
| Enable or disable AppleScript bridge ( |
|
| Temporary directory for intermediate/unnamed files. |
Tool Profiles (OFFICE_MCP_PROFILE)
To keep context usage low and tool selection fast on local models (such as LM Studio / Bionic), set OFFICE_MCP_PROFILE to expose only the apps you need:
| Tools | Est. Schema Tokens | Best For |
| 31 | ~3.6K | Daily Excel-only modeling & live recalculation on local models |
| 50 | ~5.1K | Full Excel toolset (file + live, charts, views, validation) |
| 26 | ~2.4K | Word-only document creation, styling, and live automation |
| 8 | ~0.6K | PowerPoint-only slide decks |
| 33 | ~2.9K | Secondary MCP entry for Word + PowerPoint |
| 44 | ~4.8K | Core Excel + Word tools combined |
| 75 | ~7.4K | Full Excel + Word without PowerPoint |
| 82 | ~8.0K | All Excel, Word, and PowerPoint tools |
Values are case-insensitive (
EXCEL,COMPACT,Excel,Compact,excel,compact, orXLS,Compactare equivalent) and accept any comma-separated combination ofexcel(xls/xlsx),word(doc/docx),powerpoint(ppt/pptx), andcompact.Unknown values log a warning to
stderrand fall back safely tofull.Call
check_office_status(or readoffice365://status) at any time to inspect the active profile, registered tool count, andlive_sync_mode.
Live Excel Auto-Sync (OFFICE_MCP_LIVE_SYNC)
Controls how save_workbook behaves when the target .xlsx/.xlsm file is already open in Microsoft Excel (case-insensitive: auto or off):
**
auto(default):** If the file is open in Excel with no unsaved changes, captures the window position/size, active sheet, zoom, scroll offset, and selection → closes Excel → writes viaopenpyxl→ reopens in Excel and restores the exact view. If the file has unsaved manual edits in Excel, refuses to overwrite and returns a clear warning so your edits are never lost.off: Never checks or touches live Excel duringsave_workbook.
Note on
excel_live_close:OFFICE_MCP_LIVE_SYNC=autoapplies to file-levelsave_workbook. If you explicitly callexcel_live_close, Excel will close the workbook and leave it closed—simply omitexcel_live_closeif you want the workbook to stay open in Excel.
MCP Client Configuration
For Bionic / LM Studio (Recommended Local-Model Setup)
Register two entries pointing to the same server .venv:
Microsoft 365 for Mac MCP(Excel) — always enabled:Command:
/path/to/m365-mac-mcp/.venv/bin/pythonArgs:
["/path/to/m365-mac-mcp/src/office365_mcp_server.py"]Env:
OFFICE_MCP_PROFILE=excel(orexcel,compact),OFFICE_MCP_LIVE_SYNC=autoDescription:
Microsoft 365 for Mac MCP (Excel/Office) for reading, editing, formatting, auditing, and live recalculating .xlsx/.xlsm workbooks.
M365 Word & PPT MCP— set to Hide from agent unless mentioned so it uses zero context until you@-mention it:Env:
OFFICE_MCP_PROFILE=word,powerpoint
Recommended LM Studio / Bionic settings for 30B–35B local models:
Context Length:
32768(or higher)Max Concurrent Predictions:
1Preserve Thinking:
OFFContext Overflow:
Stop at LimitProject / System Prompt tip: Add a short rule telling the assistant: "For
.xlsx/.xlsm/.docxfiles, always use theMicrosoft 365 for Mac MCPtools directly—do not open.xlsxfiles with the built-inOpenviewer or read.internal/skills/.../SKILL.md."
For Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"m365-mac-mcp": {
"command": "/path/to/m365-mac-mcp/.venv/bin/python",
"args": ["/path/to/m365-mac-mcp/src/office365_mcp_server.py"],
"env": {
"OFFICE_MCP_PROFILE": "full",
"OFFICE_MCP_LIVE_SYNC": "auto"
}
}
}
}For Cline (VS Code)
Edit your Cline MCP settings:
{
"mcpServers": {
"m365-mac-mcp": {
"command": "/path/to/m365-mac-mcp/.venv/bin/python",
"args": ["/path/to/m365-mac-mcp/src/office365_mcp_server.py"],
"env": {
"OFFICE_MCP_PROFILE": "excel,word",
"OFFICE_MCP_LIVE_SYNC": "auto"
}
}
}
}Tool Reference (82 Tools)
Excel File-Level Tools (30)
Category | Tools |
Lifecycle |
|
Inspection & Audit |
|
Worksheets |
|
Read & Write |
|
Formatting & Styles |
|
Tables & Charts |
|
Data Validation |
|
Excel Live-App Tools (18)
Category | Tools |
Lifecycle |
|
Worksheets |
|
Read & Write |
|
Views & Inspection |
|
Verified Excel for Mac 16.115 Scripting Capabilities
Feature | Support | Tool / Notes |
Live recalculation & bulk range reads | Supported |
|
Circle / Clear Invalid Data | Supported |
|
Custom Views (list & show) | Supported |
|
Native Table Styles | Supported |
|
Focus Cell / Focus Cell Color / Auto-Highlight | Manual UI only | Not exposed in |
Word File-Level Tools (18)
Category | Tools |
Lifecycle & Metadata |
|
Reading |
|
Content & Editing |
|
Styling & Tables |
|
Word Live-App Tools (8)
word_live_list_documents, word_live_create, word_live_open, word_live_read, word_live_write, word_live_replace_text, word_live_save, word_live_close
PowerPoint Tools (7)
create_presentation, add_slide, add_text_to_slide, add_image_to_slide, add_speaker_notes, save_presentation, list_active_presentations
Utility & MCP Resources (1 Tool + 1 Resource)
check_office_status— Reports installed Office apps, active profile, registered tool count, andlive_sync_mode.office365://status— Read-only MCP resource returning the same server status payload.
Example Workflows
1. Audit & Format an Excel Financial Model (File-Level)
# 1. Inspect and audit a workbook directly by file path
summary = await inspect_workbook(file_path="~/Desktop/Model.xlsx")
audit = await audit_workbook_formulas(file_path="~/Desktop/Model.xlsx")
# 2. Open, batch-format across sheets, add validation & table, and save
wb = await open_workbook(file_path="~/Desktop/Model.xlsx")
await batch_format_workbook(
workbook_id=wb["workbook_id"],
operations=[
{
"sheet_name": "Income Statement",
"freeze_panes": "B2",
"auto_fit_columns": True,
"auto_color_financial_model": True,
"styles": [
{"range": "A1:G1", "bold": True, "bg_color": "1F4E78", "font_color": "FFFFFF"},
{"range": "B2:F15", "number_format": "#,##0"}
]
}
]
)
await add_excel_table(
workbook_id=wb["workbook_id"],
sheet_name="Income Statement",
table_range="A1:G16",
table_name="IS_Table",
table_style="TableStyleLight9"
)
await add_data_validation(
workbook_id=wb["workbook_id"],
sheet_name="Income Statement",
cell_range="I1",
validation_type="list",
formula1=["Base", "Bull", "Bear"]
)
await save_workbook(workbook_id=wb["workbook_id"])2. Live Excel Recalculation Check
await excel_live_open(file_path="~/Desktop/Model.xlsx", activate=True)
baseline = await excel_live_batch_read_ranges(
workbook_name="Model.xlsx",
ranges=[
{"sheet_name": "Income Statement", "cell_range": "F2:F15"},
{"sheet_name": "Balance Sheet", "cell_range": "F12:F27"},
]
)
await excel_live_write_cell(
workbook_name="Model.xlsx",
sheet_name="Income Statement",
cell="F2",
value=450000,
recalculate=True
)
updated = await excel_live_read_range(
workbook_name="Model.xlsx",
sheet_name="Income Statement",
cell_range="F15"
)
await excel_live_save(workbook_name="Model.xlsx")3. Create a Styled Word Report
doc = await create_document(title="Executive Summary")
await add_heading(
document_id=doc["document_id"],
text="Q4 Financial Overview",
level=1,
formatting={"font_name": "Calibri", "font_color": "1F4E78"}
)
await add_table(
document_id=doc["document_id"],
rows=3,
columns=3,
data=[["Metric", "FY24", "FY25"], ["Revenue", "$391B", "$416B"], ["Net Income", "$94B", "$112B"]],
column_widths=[2.5, 1.5, 1.5],
header_formatting={"bold": True, "bg_color": "1F4E78", "font_color": "FFFFFF"},
alternating_row_color="F2F6FA",
repeat_header=True
)
await save_document(document_id=doc["document_id"], file_path="~/Desktop/Report.docx")Testing
Run the unit and integration test suite with the project virtual environment:
.venv/bin/pytest tests/test_basic.py tests/test_word_excel_rw.py -vThis runs 25 tests covering:
Excel file-level read/write, batch formatting, named styles, tables, data validation, formula sheet-reference auto-quoting & auditing, and
OFFICE_MCP_LIVE_SYNCview-restore / unsaved-edits protection.Word file-level creation, rich paragraph/table styling, search & replace, and
.docxXML attributes (w:tblHeader, borders, shading, widths).Composable
OFFICE_MCP_PROFILEfiltering, compact JSON responses, stripped schema noise, sparse A1 formula maps, and trimmed blank cells.Hardened AppleScript generation and parsing for Excel
16.115and Word16.115.1.
Troubleshooting
Permission Issues (-1743 / "Not authorized to send Apple events")
Open System Settings → Privacy & Security → Automation and enable Excel, Word, and PowerPoint for your MCP host app.
Open each Office app manually at least once to finish initial licensing/first-run dialogs.
Restart your terminal or MCP client after granting permissions.
Live Excel Calls Time Out or Hang
Check if Excel has an open modal dialog (e.g., Save As, Grant Access, or an alert) or if a cell is actively in Edit Mode (cursor blinking inside the formula bar). Press
Escin Excel and retry.create_workbook(..., open_in_excel=True)andcreate_document(..., open_in_word=True)automatically skip opening unnamed/tmpUUID files to avoid macOS sandbox Grant Access prompts; save the file to a normal folder (like~/Desktopor your workspace) before opening in the live app.
Formula Cells Show null After save_workbook
File-level
openpyxlwrites formulas to disk without running Excel's calculation engine, so cached evaluated values are empty until Excel recalculates them. Useexcel_live_open+excel_live_read_range(orOFFICE_MCP_LIVE_SYNC=autowith the file open in Excel) to evaluate and read live calculated values.
Import / Environment Errors
Ensure your MCP client config points directly to
.venv/bin/pythonrather than systempython3.Verify dependencies with
.venv/bin/pip install -r requirements.txt.
Project Structure
m365-mac-mcp/
├── src/
│ ├── office365_mcp_server.py # Main MCP server, tool registration & profiles
│ ├── controllers/
│ │ ├── excel_controller.py # File-level Excel (openpyxl) + live auto-sync
│ │ ├── word_controller.py # File-level Word (python-docx) + rich styling
│ │ └── powerpoint_controller.py # File-level PowerPoint (python-pptx)
│ ├── integrations/
│ │ └── applescript_bridge.py # Serialized, hardened macOS AppleScript bridge
│ └── utils/
│ ├── config.py # Env & JSON configuration
│ ├── logger.py # stderr-only structured logging
│ └── validators.py # Input & path validation
├── tests/
│ ├── test_basic.py
│ └── test_word_excel_rw.py
├── requirements.txt
└── README.mdAuthor & License
Author: Sterling Jimenez, Ph.D. (stejimenez@gmail.com)
License: MIT License — see LICENSE for details.
Acknowledgments
Built with the Model Context Protocol (MCP)
Uses
openpyxl,python-docx, andpython-pptxfor file-level Office manipulationUses macOS AppleScript (
osascript) for native Microsoft Excel and Word automationBased on the original
macos-office365-mcp-serverproof-of-concept by Adam Bluhm (https://www.linkedin.com/in/bluhmadam/)
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Create and manage documents, spreadsheets, and presentations from your AI assistant.
File tools for your AI chat: PDF tables to Excel, merge PDFs, images to PDF, fill PDF forms.
Online office suite for AI agents: edit docs, sheets, slides and PDFs in browser or via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to create and manipulate Microsoft Office documents (PowerPoint, Word, Excel) on macOS via AppleScript automation.MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to read, write, format, and analyze Excel files with 34 tools, including real-time editing on macOS with Microsoft Excel.3417MIT
- 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
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create and process office documents locally, including generating branded PDF, Word, Excel, and editable PowerPoint files from templates and themes, plus reading, OCR, form-filling, manipulation, and conversion of PDFs.1MIT