# 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 的全部条件格式（快速清理用）