# Office MCP Server

MCP server for Microsoft Office file operations. Read, write, and create **Excel (.xlsx)**, **Word (.docx)**, and **PowerPoint (.pptx)** files directly from your local filesystem.

Works with any MCP-compatible client (Claude Desktop, Trae SOLO, VS Code via MCP extension, etc.).

## Features

### Excel

| Tool | Function |
|------|----------|
| `office_read_excel` | Read data from Excel files (specify sheet and range) |
| `office_write_excel` | Write or append data to existing Excel files |
| `office_create_excel` | Create new Excel files with headers, data, and auto-sized columns |
| `office_get_excel_info` | List all sheets with dimensions |
| `office_excel_create_table` | **Create formatted Excel tables (超级表/ListObject) with styles, filter buttons, and totals row** |
| `office_excel_set_formula` | Set formulas in cells (e.g. `SUM(A2:B2)`) |
| `office_excel_fill_formula` | Fill formulas across a range of cells |
| `office_excel_merge_cells` | Merge or unmerge cell ranges |
| `office_excel_add_auto_filter` | Add auto filter to a data range |
| `office_excel_set_styles` | Apply advanced cell formatting (font, fill, border, alignment, number format) |
| `office_excel_add_comment` | Add comments/notes to cells |
| `office_excel_add_image` | Insert images into worksheets |
| `office_excel_rename_sheet` | Rename worksheets |
| `office_excel_add_conditional_formatting` | **Add conditional formatting: data bars, color scales, icon sets, cell rules** |
| `office_excel_add_data_validation` | **Add data validation: dropdown lists, number ranges, custom rules** |
| `office_excel_freeze_panes` | **Freeze rows/columns to keep them visible while scrolling** |

### Word

| Tool | Function |
|------|----------|
| `office_create_word` | **Create Word documents with rich formatting: headings, paragraphs, formatted tables (borders, shading, header rows, column widths), images, hyperlinks, page breaks, text styling (bold, italic, underline, strikethrough, color, highlight, superscript, subscript), alignment, lists, headers/footers with page numbers, page orientation, margins, table of contents** |
| `office_read_word` | Get basic document info |

### PowerPoint

| Tool | Function |
|------|----------|
| `office_create_powerpoint` | Create presentations with title, subtitle, and bullet content slides |
| `office_add_powerpoint_slides` | Append slides to an existing presentation |
| `office_ppt_add_chart` | Generate single-slide presentations with charts (bar, pie, line, area, radar, bubble, etc.) |
| `office_ppt_add_shape` | Draw shapes (rectangles, circles, stars, arrows, hearts, etc.) |
| `office_ppt_add_image` | Insert images into slides |
| `office_ppt_add_table` | Create formatted table slides |
| `office_ppt_add_master_slide` | **Create slide masters (templates) with consistent branding** |
| `office_ppt_add_animation` | **Create animated slides with fade, fly, zoom, bounce effects** |

## Installation

### Prerequisites

- Node.js >= 18
- npm

### Setup

```bash
git clone https://github.com/Alex-eng-ux/office-mcp-server.git
cd office-mcp-server
npm install
npm run build
```

## Configuration

Add the server to your MCP configuration file (`mcp.json`):

```json
{
  "mcpServers": {
    "Office MCP": {
      "command": "node",
      "args": ["path/to/office-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}
```

**Configuration file locations:**

| Client | File Path |
|--------|-----------|
| Trae / Trae SOLO | `%APPDATA%\TRAE SOLO CN\User\mcp.json` |
| VS Code + MCP extension | `.vscode/mcp.json` in project root |
| Claude Desktop | `claude_desktop_config.json` |

## Usage Examples

### Excel

Create a budget spreadsheet:

```
Create an Excel file at ./budget.xlsx with headers ["项目", "预算", "实际", "差异"]
and rows [["研发", 100000, 95000, 5000], ["市场", 50000, 52000, -2000]]
```

Read data from an existing file:

```
Read Sheet1 from ./report.xlsx, range A1:D10
```

Create a formatted Excel table (超级表) with alternating row colors and totals row:

```
Create a table in ./sales.xlsx sheet "Sheet1":
name: "SalesTable"
columns: ["产品" (name), "销量" (sum), "金额" (sum)]
rows: [["A产品", 120, 15000], ["B产品", 85, 10200], ["C产品", 200, 28000]]
style: { theme: "TableStyleMedium9", showRowStripes: true, showFirstColumn: true }
totalsRow: true
```

Set formulas and apply cell formatting:

```
- Set formula in ./budget.xlsx sheet "Sheet1" cell D2: "B2-C2" (差异 = 预算 - 实际)
- Fill formula from D2 to D10 in ./budget.xlsx sheet "Sheet1"
- Apply styles to A1:D1 in ./budget.xlsx: bold font, blue background (#4472C4), white text, centered
- Set number format "¥#,##0" for range C2:D10
- Add auto filter to A1:D10
- Merge cells A11:D11 for a title row
- Add comment to B5: "需部门负责人确认" author: "财务部"
```

Add conditional formatting:

```
- Add data bars to C2:C10 in ./sales.xlsx: color "4472C4", showValue: true
- Add color scale to D2:D10: minColor "63BE7B", midColor "FFEB84", maxColor "F8696B"
- Add icon set (3Arrows) to B2:B10: showValue: true
- Add cell rule to C2:C10: greaterThan 15000, fill color "92D050"
```

Add data validation:

```
- Add dropdown list to A2:A10: type "list", formulae: ['"选项1,选项2,选项3"']
- Add integer range to B2:B10: type "whole", operator "between", formulae: [1, 100]
```

Freeze panes:

```
- Freeze first row in ./report.xlsx sheet "Sheet1": freezeType "row", rows: 1
- Freeze first column: freezeType "column", cols: 1
```

### Word

Generate a meeting report with rich formatting:

```
Create a Word document at ./meeting.docx with:
- Heading 1: "项目周报"
- Paragraph: "本周进展顺利。"
- Heading 2: "完成事项"
- Bullet: "功能A已上线"
- Bullet: "Bug修复完成"
- Table: headers ["任务", "状态", "负责人"]
  with formatting: header shading (#4472C4), borders, column widths [2, 2, 2]
- Table rows: ["登录模块", "已完成", "张三"], ["支付功能", "测试中", "李四"]
- Page break
- Heading 2: "参考资料"
- Hyperlink: "点击查看项目文档" -> https://example.com/docs
- Paragraph: "红色粗体警告文字" bold: true, color: "FF0000"
- Paragraph: "居中对齐段落" alignment: "center"
```

Create a landscape document with headers, footers and page numbers:

```
Create a Word document at ./report.docx with:
- Heading 1: "年度汇报", alignment: "center"
- Paragraph: "内容..."
Options: orientation: "landscape", margins: { top: 0.8, bottom: 0.8, left: 1, right: 1 }, header: "公司机密", footer: "第 1 页", showPageNumber: true
```

Create a document with table of contents:

```
Create a Word document at ./report.docx with:
- TOC (table of contents)
- Heading 1: "第一章 概述"
- Paragraph: "..."
- Heading 2: "1.1 背景"
- Paragraph: "..."
- Heading 1: "第二章 方案"
- ...
```

### PowerPoint

Create a presentation:

```
Create a PowerPoint at ./report.pptx with 3 slides:
Slide 1: title "季度汇报", subtitle "2026 Q2"
Slide 2: title "核心数据", bullets ["营收增长25%", "用户突破100万"]
Slide 3: title "下一步计划", bullets ["优化性能", "扩展新功能"]
```

Add a bar chart:

```
Create a chart at ./chart.pptx:
type: bar
data: [labels: ["Q1","Q2","Q3","Q4"], name: "营收", values: [120, 150, 180, 220]]
options: showLegend: true, barDirection: "col"
```

Add a shape:

```
Create a shape slide at ./shape.pptx:
shape: "star5"
options: { x: 2, y: 1, w: 4, h: 4, fillColor: "FFD700" }
```

Create a master slide template:

```
Create a master slide at ./template.pptx:
title: "CORPORATE"
background: { color: "1F497D" }
objects: [{ type: "text", text: "公司机密", options: { x: 0.5, y: 7, w: 9, h: 0.5, fontSize: 10, color: "AAAAAA" } }]
slideNumber: { x: 9.2, y: 7, fontSize: 10, color: "AAAAAA" }
```

Create an animated slide:

```
Create an animated slide at ./animated.pptx:
title: "项目进展"
content: ["需求分析已完成", "系统设计已完成", "开发实现中"]
animations: [{ type: "fade", delay: 0, duration: 500, on: "onClick" }, { type: "fly", delay: 200, duration: 600, on: "afterPrevious" }]
```

### Supported Chart Types

| Type | Description |
|------|-------------|
| `bar` | Bar chart (clustered, stacked, percentStacked) |
| `bar3D` | 3D bar chart |
| `line` | Line chart |
| `pie` | Pie chart |
| `area` | Area chart |
| `doughnut` | Doughnut chart |
| `radar` | Radar chart |
| `scatter` | Scatter chart |
| `bubble` | Bubble chart |

### Common Shapes

`rect`, `ellipse`, `triangle`, `star5`, `heart`, `diamond`, `cloud`, `lightningBolt`, `smileyFace`, `chevron`, `pentagon`, `hexagon`, `octagon`, `moon`, `sun`, `leftArrow`, `rightArrow`, `upArrow`, `downArrow`, `cube`, `plus`, `wave`, `funnel`, `ribbon`, `line` — and 150+ more.

## Development

```bash
# Watch mode
npm run dev

# Build
npm run build

# Start
npm start
```

## Project Structure

```
office-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry, tool registration
│   ├── types.ts              # Shared type definitions
│   └── services/
│       ├── excel.ts          # Excel operations
│       ├── word.ts           # Word operations
│       └── powerpoint.ts     # PowerPoint operations (charts, shapes, images, tables)
├── test-excel-advanced.mjs   # Excel advanced features test script
├── test-word-advanced.mjs    # Word advanced features test script
├── test-new-features.mjs     # Conditional formatting, data validation, freeze panes, TOC, master, animation test
├── package.json
├── tsconfig.json
└── .gitignore
```

## License

MIT