README - macos-office365-mcp-server by vairpower

macOS Office 365 MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to create and manipulate Microsoft Office documents (PowerPoint, Word, and Excel) on macOS.

Features

PowerPoint

Create presentations with custom titles and themes
Add slides with various layouts
Insert text, images, and speaker notes
Save presentations in multiple formats

Word

Create documents from scratch or templates
Add headings, paragraphs, lists, and tables
Apply text formatting and styles
Save documents in multiple formats

Excel

Create workbooks with multiple worksheets
Write data to cells and ranges
Add formulas and calculations
Create charts (bar, line, pie)
Apply cell formatting and styles
Save workbooks in multiple formats

Prerequisites

System Requirements

macOS 10.15 or later
Python 3.8 or later
Microsoft Office for Mac (PowerPoint, Word, and/or Excel)

Python Dependencies

pip install mcp
pip install python-pptx
pip install python-docx
pip install openpyxl
pip install aiofiles

Installation

Clone the repository

git clone https://github.com/vAirpower/macos-office365-mcp-server.git
cd macos-office365-mcp-server

Install dependencies
```
pip install -r requirements.txt
```
Set up macOS permissions

The server uses AppleScript to control Office applications. You need to grant permissions:

a. Open System Preferences → Security & Privacy → Privacy b. Select Automation in the left sidebar c. Find your terminal application (Terminal, iTerm2, VS Code, etc.) d. Check the boxes for:
- Microsoft PowerPoint
- Microsoft Word
- Microsoft Excel
If prompted when first running the server, click "OK" to allow automation.

Configuration

MCP Client Configuration

Add the server to your MCP client configuration:

For Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "office365": {
      "command": "python",
      "args": ["/path/to/macos-office365-mcp-server/src/office365_mcp_server.py"]
    }
  }
}

For Cline (VS Code)

Edit your Cline MCP settings:

{
  "mcpServers": {
    "office365": {
      "command": "python",
      "args": ["/path/to/macos-office365-mcp-server/src/office365_mcp_server.py"]
    }
  }
}

Usage

Once configured, the AI assistant can use the following tools:

PowerPoint Tools

create_presentation - Create a new presentation
add_slide - Add a slide to a presentation
add_text_to_slide - Add text content to a slide
add_image_to_slide - Add an image to a slide
add_speaker_notes - Add speaker notes to a slide
save_presentation - Save the presentation to a file

Word Tools

create_document - Create a new document
add_heading - Add a heading to a document
add_paragraph - Add a paragraph with optional formatting
add_list - Add a bulleted or numbered list
add_table - Add a table with data
save_document - Save the document to a file

Excel Tools

create_workbook - Create a new workbook
add_worksheet - Add a worksheet to a workbook
write_cell - Write data to a specific cell
write_range - Write data to a range of cells
add_formula - Add a formula to a cell
create_chart - Create a chart from data
save_workbook - Save the workbook to a file
list_worksheets - List all worksheets in a workbook

Utility Tools

list_active_presentations - List all open presentations
list_active_documents - List all open documents
list_active_workbooks - List all open workbooks
check_office_status - Check if Office apps are available

Example Usage

Creating a PowerPoint Presentation

# AI Assistant can execute:
result = await create_presentation(
    title="Q4 Sales Report",
    theme="modern"
)

slide = await add_slide(
    presentation_id=result["presentation_id"],
    layout="Title and Content"
)

await add_text_to_slide(
    slide_id=slide["slide_id"],
    text="Revenue increased by 25%",
    placeholder="content"
)

await save_presentation(
    presentation_id=result["presentation_id"],
    file_path="~/Desktop/Q4_Sales.pptx"
)

Creating a Word Document

# AI Assistant can execute:
doc = await create_document(title="Project Proposal")

await add_heading(
    document_id=doc["document_id"],
    text="Executive Summary",
    level=1
)

await add_paragraph(
    document_id=doc["document_id"],
    text="This proposal outlines our approach...",
    formatting={"font_size": 12, "font_name": "Arial"}
)

await save_document(
    document_id=doc["document_id"],
    file_path="~/Desktop/proposal.docx"
)

Creating an Excel Workbook

# AI Assistant can execute:
workbook = await create_workbook(title="Sales Analysis")

# Add data
data = [
    ["Product", "Q1", "Q2", "Q3", "Q4"],
    ["Laptops", 100, 150, 200, 180],
    ["Tablets", 80, 90, 110, 120],
    ["Phones", 200, 250, 300, 350]
]

await write_range(
    workbook_id=workbook["workbook_id"],
    sheet_name="Sheet1",
    start_cell="A1",
    data=data,
    formatting={"bold": True}  # Bold headers
)

# Add a formula
await add_formula(
    workbook_id=workbook["workbook_id"],
    sheet_name="Sheet1",
    cell="F2",
    formula="=SUM(B2:E2)"
)

# Create a chart
await create_chart(
    workbook_id=workbook["workbook_id"],
    sheet_name="Sheet1",
    chart_type="bar",
    data_range="A1:E4",
    chart_title="Quarterly Sales",
    position="G2"
)

await save_workbook(
    workbook_id=workbook["workbook_id"],
    file_path="~/Desktop/sales_analysis.xlsx"
)

Troubleshooting

Permission Issues

If you see "Not authorized to send Apple events", ensure:

Your terminal has automation permissions for Office apps
Office applications are installed and have been opened at least once
You may need to restart your terminal after granting permissions

Import Errors

If you see import errors:

Ensure all dependencies are installed: pip install -r requirements.txt
Check Python version: python --version (should be 3.8+)
Verify MCP is installed: pip show mcp

Office Not Found

If Office applications aren't detected:

Ensure Microsoft Office for Mac is installed
Try opening PowerPoint/Word/Excel manually first
Check if Office is installed in the standard Applications folder

Development

Project Structure

macos-office365-mcp-server/
├── src/
│   ├── office365_mcp_server.py    # Main MCP server
│   ├── controllers/
│   │   ├── powerpoint_controller.py
│   │   ├── word_controller.py
│   │   └── excel_controller.py
│   ├── integrations/
│   │   └── applescript_bridge.py  # AppleScript automation
│   └── utils/
│       ├── config.py
│       ├── logger.py
│       └── validators.py
├── requirements.txt
└── README.md

Adding New Features

Add new methods to the appropriate controller
Register new tools in office365_mcp_server.py
Update this README with usage examples

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Add tests for new functionality
Submit a pull request

Support

For issues and questions:

Open an issue on GitHub
Check existing issues for solutions
Ensure you've followed all setup steps

Acknowledgments

Built with the Model Context Protocol (MCP)
Uses python-pptx, python-docx, and openpyxl for document manipulation
AppleScript integration for native Office control