MCP Sheet Parser

MCP Sheet Parser 是一个基于模型上下文协议（Model Context Protocol, MCP）构建的服务器。它为 AI 代理提供解析、转换和修改电子表格文件的能力。

该服务器通过标准输入输出（stdio）与兼容 MCP 的客户端（如 Claude Desktop）通信，允许 AI 代理以工具调用的方式处理包括 XLSX、XLSM、XLS、XLSB 和 CSV 在内的多种表格格式。

工作原理

当 AI 代理需要处理一个表格文件时，它会通过 MCP 向本服务器发送一个 JSON-RPC 请求。服务器接收请求，调用内部相应的处理函数，并将结构化的 JSON 数据返回给代理。这个过程使得 AI 代理能够理解和操作传统上难以访问的表格数据。

其基本架构如下：

MCP 客户端: AI 代理的运行环境，例如 Claude Desktop 或其他 IDE。
通信协议: 客户端与服务器之间通过标准输入输出（stdio）进行 JSON-RPC 通信。
MCP 服务器: 本项目，一个独立的 Python 进程，负责监听和响应来自客户端的请求。
核心服务: 服务器内部的业务逻辑，调用特定的解析器或转换器来完成任务。

核心功能

服务器提供三个核心工具来完成一个完整的数据处理闭环：

parse_sheet: 解析电子表格文件。此工具将文件内容转换为结构化的 JSON 对象，该对象为 AI 代理的上下文进行了优化。默认情况下，它只返回文件的概览信息（如尺寸、列名和数据预览），以避免消耗过多的令牌。代理可以根据需要请求获取完整数据或样式信息。
convert_to_html: 将电子表格转换为 HTML 文件。此功能可以保留原始文件中的大部分样式，包括字体、颜色、边框和合并单元格，使得数据可以在浏览器中进行可视化查阅。
apply_changes: 将 AI 代理修改后的 JSON 数据写回到原始电子表格文件中。此工具接收从 parse_sheet 获取并由代理处理过的数据，完成数据的修改和保存。

安装与配置

前置要求

Python 3.8 或更高版本
uv (推荐的包管理器)

安装步骤

git clone https://github.com/yuqie6/MCP-Sheet-Parser.git
cd MCP-Sheet-Parser
uv sync

客户端配置

要将此服务器与兼容 MCP 的客户端一同使用，需要在客户端的配置文件中进行设置。

以 Claude Desktop 为例，配置文件路径如下：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

在配置文件中添加以下 mcpServers 条目：

{
  "mcpServers": {
    "sheet-parser": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/MCP-Sheet-Parser-cot",
        "run",
        "main.py"
      ]
    }
  }
}

注意: 请将 /path/to/MCP-Sheet-Parser-cot 替换为本项目的绝对路径。

使用指南

配置完成后，重启客户端即可开始使用。您可以向 AI 代理发出自然语言指令来处理表格文件。

解析文件: "请解析 /path/to/sales.xlsx 文件并提供一份摘要。"
转换文件: "将 /path/to/data.csv 转换为 HTML 文件。"
修改数据: "读取库存表 /path/to/inventory.xlsx，然后将所有'笔记本电脑'的数量增加10，最后保存修改。"

工具定义

`parse_sheet`

解析一个表格文件，返回其结构化的 JSON 表示。

file_path (字符串, 必需): 表格文件的绝对路径。
sheet_name (字符串, 可选): 需要解析的特定工作表名称。如果留空，则解析第一个工作表。
range_string (字符串, 可选): 指定单元格范围，例如 "A1:D10"。
include_full_data (布尔值, 可选, 默认 false): 是否返回所有行的数据。
include_styles (布尔值, 可选, 默认 false): 是否在返回的数据中包含样式信息。
preview_rows (整数, 可选, 默认 5): 在概览模式下，返回的数据预览行数。
max_rows (整数, 可选): 限制返回的最大行数，用于处理大型文件。

`convert_to_html`

将一个表格文件转换为 HTML。

file_path (字符串, 必需): 源表格文件的绝对路径。
output_path (字符串, 可选): 输出 HTML 文件的路径。如果留空，则在源文件相同目录下生成同名 HTML 文件。
sheet_name (字符串, 可选): 指定要转换的单个工作表名称。如果留空，则转换所有工作表。
page_size (整数, 可选, 默认 100): 分页时每页显示的行数。
page_number (整数, 可选, 默认 1): 查看分页结果时的页码。
header_rows (整数, 可选, 默认 1): 将文件顶部的指定行数视为固定表头。

`apply_changes`

将修改后的数据写回表格文件。

file_path (字符串, 必需): 目标文件的绝对路径。
table_model_json (对象, 必需): 从 parse_sheet 工具获取并由 AI 代理修改后的数据对象。
create_backup (布尔值, 可选, 默认 true): 是否在写入前创建原始文件的备份。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。