# Excel Tools MCP
一个提供读取、写入和分析 Excel 文件工具的 MCP 服务器。基于 Python、`pandas` 和 `openpyxl` 构建。
## 安装使用
### 1.在 Glosc Copilot 中使用
- 下载并安装 [Glosc Copilot](https://github.com/glosc-ai/Glosc-Copilot/releases)
- 从 [Excel Tools](https://www.glosc.ai/store/plugins/excel-tools) 点击 “安装”
### 2.配置使用
```json
{
"servers": {
"Excel-Tools": {
"type": "stdio",
"command": "python",
"args": [
"main.py"
]
}
}
}
```
## MCP 工具
- **get_excel_sheet_names(filepath)**:
获取 Excel 文件中的工作表名称列表。
- **read_excel_sheet(filepath, sheet_name)**:
读取指定工作表的数据。返回一个兼容 JSON 的记录列表（字典列表）。
- **read_all_excel_sheets(filepath)**:
读取 Excel 文件中的所有工作表。返回一个字典，键为工作表名称，值为记录列表。
- **create_excel_file(filepath, data, sheet_name="Sheet1")**:
创建一个新的 Excel 文件。
`data` 必须是表示字典列表的 JSON 字符串（例如：`[{"col1": 1, "col2": "a"}, ...]`）。
- **add_excel_sheet(filepath, data, sheet_name)**:
向现有的 Excel 文件添加一个新的工作表（如果文件存在则追加）。
`data` 必须是表示字典列表的 JSON 字符串。
- **analyze_excel_structure(filepath, output_path=None)**:
分析 Excel 文件的结构（行数、列名、数据类型、空值计数）。
如果提供了 `output_path`，则将分析结果保存为 JSON 文件；否则，返回 JSON 字符串。
## 扩展：常用 Excel 编辑/格式工具
下面这些工具基于 `openpyxl`，用于修改 Excel 的样式与格式（列宽行高、合并、字体、背景、边框、格式等）。
- **set_excel_dimensions(filepath, sheet_names=None, column_widths=None, row_heights=None)**:
调整列宽/行高。
- `sheet_names`: 传 `null` 表示对所有工作表生效；或传 `['Sheet1','Sheet2']`。
- `column_widths`: 如 `{ "A": 20, "C": 12 }`（列可用字母或数字字符串）。
- `row_heights`: 如 `{ "1": 25, "2": 18 }`（行号建议用字符串键）。
- **merge_excel_cells(filepath, ranges, sheet_names=None, unmerge=false)**:
合并/取消合并单元格。
- `ranges`: 如 `["A1:C1", "D2:D5"]`
- `unmerge=true` 表示取消合并。
- **set_excel_font(filepath, targets, sheet_names=None, name=None, size=None, bold=None, italic=None, underline=None, color=None)**:
修改字体样式。
- `targets`: 单元格或范围，如 `["A1", "B2:C3"]`
- `color`: 支持 `"#RRGGBB"` / `"RRGGBB"` / `"FFRRGGBB"`
- **set_excel_fill(filepath, targets, sheet_names=None, fill_color=None, pattern="solid", clear=false)**:
修改/清空单元格背景。
- **set_excel_number_format(filepath, targets, number_format, sheet_names=None)**:
设置单元格格式（数字/日期/文本等），例如：
- `"0.00"`、`"yyyy-mm-dd"`、`"@"`（文本）
- **set_excel_border(filepath, targets, sheet_names=None, style="thin", color=None, sides=None, remove=false)**:
添加/移除边框。
- `sides`: 默认四边，可传 `['left','right','top','bottom']`
- `remove=true` 表示移除对应边框
- **set_excel_alignment(filepath, targets, sheet_names=None, horizontal=None, vertical=None, wrap_text=None, text_rotation=None)**:
设置对齐与换行（常用：居中、自动换行）。
- **apply_excel_operations(filepath, operations)**:
批量执行多步操作（一次打开/保存，性能更好，适合“对多张表格做一组统一操作”）。
- `operations` 是 JSON 字符串数组，每项包含 `op` 字段；支持：
`set_dimensions` / `merge_cells` / `set_font` / `set_fill` / `set_number_format` / `set_alignment` / `set_border`
/ `freeze_panes` / `set_auto_filter` / `set_sheet_protection` / `set_hidden` / `conditional_formatting`
示例（对所有 sheet：A 列宽 20，标题行加粗居中并加底色）：
```json
[
{"op":"set_dimensions","sheet_names":null,"column_widths":{"A":20}},
{"op":"set_font","sheet_names":null,"targets":["1:1"],"bold":true},
{"op":"set_alignment","sheet_names":null,"targets":["1:1"],"horizontal":"center","vertical":"center","wrap_text":true},
{"op":"set_fill","sheet_names":null,"targets":["1:1"],"fill_color":"#F2F2F2"}
]
```
## 扩展：冻结/筛选/保护/隐藏/条件格式
- **freeze_excel_panes(filepath, cell=None, sheet_names=None)**:
冻结窗格。
- `cell`: 例如 `"B2"` 表示冻结首行首列；传 `null` 表示取消冻结。
- **set_excel_auto_filter(filepath, ref=None, sheet_names=None, clear=false)**:
设置/清空自动筛选范围。
- `ref`: 例如 `"A1:D200"`
- `clear=true` 表示清空筛选范围
- **protect_excel_sheet(filepath, protect=true, sheet_names=None, password=None)**:
设置工作表保护（支持指定密码）。
- `protect=false` 可关闭保护
- **set_excel_hidden(filepath, sheet_names=None, hide_rows=None, hide_cols=None, hidden=true)**:
隐藏/取消隐藏行列。
- `hide_rows`: 例如 `[2,3,4]`
- `hide_cols`: 例如 `["B","D"]`
- `hidden=false` 表示取消隐藏
- **set_excel_conditional_formatting(filepath, ranges, rule=None, sheet_names=None, clear=false)**:
添加/清空条件格式。
- `rule` 为 JSON 字符串；支持：
- `color_scale`: `{ "type":"color_scale", "start":"#63BE7B", "mid":"#FFEB84", "end":"#F8696B" }`
- `cell_is`: `{ "type":"cell_is", "operator":"greaterThan", "formula":["0"], "fill":"#FFF2CC" }`
- `formula`: `{ "type":"formula", "formula":["$A2>0"], "fill":"#C6EFCE" }`
- `clear=true` 会清空指定 sheet 的全部条件格式（快速清理用）
