Skip to main content
Glama
yuqie6

MCP Sheet Parser

by yuqie6
OverviewSchemaRelated ServersScoreDiscussions
Python

MCP Sheet Parser

License: MIT Python 3.8+ MCP

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

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

工作原理

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

其基本架构如下：

  1. MCP 客户端: AI 代理的运行环境，例如 Claude Desktop 或其他 IDE。

  2. 通信协议: 客户端与服务器之间通过标准输入输出（stdio）进行 JSON-RPC 通信。

  3. MCP 服务器: 本项目，一个独立的 Python 进程，负责监听和响应来自客户端的请求。

  4. 核心服务: 服务器内部的业务逻辑，调用特定的解析器或转换器来完成任务。

Related MCP server: mcp-google-sheets

核心功能

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

  1. parse_sheet: 解析电子表格文件。此工具将文件内容转换为结构化的 JSON 对象，该对象为 AI 代理的上下文进行了优化。默认情况下，它只返回文件的概览信息（如尺寸、列名和数据预览），以避免消耗过多的令牌。代理可以根据需要请求获取完整数据或样式信息。

  2. convert_to_html: 将电子表格转换为 HTML 文件。此功能可以保留原始文件中的大部分样式，包括字体、颜色、边框和合并单元格，使得数据可以在浏览器中进行可视化查阅。

  3. 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 文件。

Available Tools

3 tools
apply_changesA

将修改后的数据写回Excel/CSV文件，完成数据编辑闭环。接受parse_sheet返回的JSON格式数据（修改后）。保留原文件格式和样式，默认创建备份文件防止数据丢失。支持添加、删除、修改行和单元格数据。

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes需要写回数据的目标文件的绝对路径。
table_model_jsonYes从 `parse_sheet` 工具获取并修改后的 TableModel JSON 数据。
create_backupNo【可选】是否在写入前创建原始文件的备份。默认为 `true`，以防意外覆盖。

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: it preserves original file formatting/styles, creates backup files by default to prevent data loss, and supports specific operations (add, delete, modify rows and cell data). This covers important mutation behavior, safety mechanisms, and operational scope that aren't in the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured in three sentences: purpose statement, input requirements, and behavioral details. Every sentence adds value - no repetition or fluff. It's appropriately sized for a tool with 3 parameters and important behavioral characteristics.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description does well by explaining the write operation, safety mechanisms (backups), and supported edit types. It could be more complete by mentioning error conditions or what happens if the file_path doesn't exist, but it covers the essential context given the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds minimal parameter semantics beyond the schema - it mentions the JSON format comes from 'parse_sheet' (which is also in the schema) and implies the backup default is true. This meets the baseline expectation when schema coverage is high.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('将修改后的数据写回Excel/CSV文件' - write modified data back to Excel/CSV files) and resource (Excel/CSV files). It distinguishes from sibling tools like 'parse_sheet' (which reads data) and 'convert_to_html' (which converts format) by focusing on the write-back operation to complete the data editing loop.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context about when to use this tool: after modifying data from 'parse_sheet' to complete the editing workflow. It mentions the input format requirement ('接受parse_sheet返回的JSON格式数据'), establishing a prerequisite relationship. However, it doesn't explicitly state when NOT to use it or compare with alternatives beyond the implied workflow.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_to_htmlA

将Excel/CSV文件转换为可在浏览器中查看的HTML文件。保留原始样式、颜色、字体等格式。支持多工作表文件，可选择特定工作表或转换全部。大文件可使用分页功能。返回结构化JSON，包含成功状态、生成的文件信息和转换摘要。

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes源表格文件的绝对路径，支持 .csv, .xlsx, .xls, .xlsb, .xlsm 格式。
output_pathNo输出HTML文件的路径。如果留空，将在源文件目录中生成一个同名的 .html 文件。
sheet_nameNo【可选】要转换的单个工作表的名称。如果留空，将转换文件中的所有工作表。
page_sizeNo【可选】分页时每页显示的行数。默认为100行。用于控制大型文件转换后HTML的单页大小。
page_numberNo【可选】要查看的页码，从1开始。默认为1。用于浏览大型文件的特定页面。
header_rowsNo【可选】将文件顶部的指定行数视为表头。默认为 1。

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden and discloses key behavioral traits: it preserves original styling, supports multi-sheet files with selective conversion, handles large files via pagination, and returns structured JSON with status and summary. It does not mention error handling or performance limits, but covers core functionality well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded with the core purpose, followed by key features and return format in a single, efficient sentence. Every phrase adds value (e.g., 'preserve original style', 'supports multi-sheet files', 'returns structured JSON') with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, file conversion with formatting) and no output schema, the description is mostly complete: it covers the conversion process, formatting preservation, multi-sheet support, pagination for large files, and JSON return structure. It lacks details on error cases or output schema specifics, but is sufficient for agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 6 parameters. The description adds no additional parameter semantics beyond what's in the schema, such as format details or usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with specific verbs ('convert', 'preserve', 'return') and resources ('Excel/CSV files', 'HTML files'), distinguishing it from siblings like 'apply_changes' and 'parse_sheet' by focusing on format conversion rather than data manipulation or parsing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for converting spreadsheet files to HTML with formatting preservation, but does not explicitly state when to use this tool versus alternatives like 'parse_sheet' or provide exclusions (e.g., non-tabular data). It mentions support for large files and pagination as contextual features.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

parse_sheetA

解析Excel/CSV文件为结构化JSON数据。默认返回文件概览信息（行数、列数、数据类型、前几行预览），避免上下文过载。LLM可通过参数控制是否获取完整数据、样式信息等。适合数据分析和处理，修改后可用apply_changes写回。

ParametersJSON Schema
NameRequiredDescriptionDefault
file_pathYes目标表格文件的绝对路径，支持 .csv, .xlsx, .xls, .xlsb, .xlsm 格式。
sheet_nameNo【可选】要解析的工作表名称。如果留空，使用第一个工作表。
range_stringNo【可选】单元格范围，如'A1:D10'。指定范围时会返回该范围的完整数据。
include_full_dataNo【可选，默认false】是否返回完整数据。false时只返回概览和预览，true时返回所有行数据。大文件建议先查看概览。
include_stylesNo【可选，默认false】是否包含样式信息（字体、颜色、边框等）。样式信息会显著增加数据量。
preview_rowsNo【可选，默认5】预览行数。当include_full_data为false时，返回前N行作为数据预览。
max_rowsNo【可选】最大返回行数。用于限制大文件的数据量，超出部分会被截断并提示。

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: default returns overview info to avoid context overload, mentions performance considerations for large files, and hints at output structure (概览信息 like row count, column count, data types, preview). However, it doesn't detail error handling, file size limits, or exact JSON schema, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it starts with the core purpose, explains default behavior and rationale, mentions parameter control, and ends with usage context. Every sentence adds value without redundancy, and it's front-loaded with essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (7 parameters, no annotations, no output schema), the description does a good job of covering purpose, behavior, and usage. It mentions the output includes overview info and previews, compensating for the lack of output schema. However, it doesn't fully detail error cases or exact return formats, leaving some ambiguity for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 7 parameters thoroughly. The description adds some context by mentioning 'LLM可通过参数控制是否获取完整数据、样式信息等' (LLM can use parameters to control whether to get full data, style info, etc.), which reinforces parameter purposes, but doesn't provide significant additional semantics beyond what's in the schema. Baseline 3 is appropriate given high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '解析Excel/CSV文件为结构化JSON数据' (parse Excel/CSV files into structured JSON data). It specifies the resource (Excel/CSV files) and the action (parse into JSON), and distinguishes it from sibling tools by mentioning '修改后可用apply_changes写回' (after modification, can use apply_changes to write back), showing it's for reading/parsing rather than conversion or writing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use it: '适合数据分析和处理' (suitable for data analysis and processing). It mentions an alternative tool ('apply_changes') for writing back modifications, but doesn't explicitly state when not to use it or compare it to 'convert_to_html'. The guidance is helpful but not fully comprehensive regarding all sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updates
    • First observedapply_changes
    • First observedconvert_to_html
    • First observedparse_sheet
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: parse_sheet reads data, convert_to_html transforms it for viewing, and apply_changes writes modifications back. There is no overlap in functionality, making tool selection straightforward for an agent.

Naming Consistency4/5

The tools follow a consistent verb_noun pattern (parse_sheet, convert_to_html, apply_changes), which is predictable and readable. The minor deviation is that 'apply_changes' uses a plural noun while others use singular, but this does not hinder usability.

Tool Count5/5

With 3 tools, the server is well-scoped for parsing and manipulating spreadsheet files. Each tool serves a distinct and necessary function in the data workflow, avoiding bloat or thin coverage.

Completeness4/5

The tools cover core operations: reading (parse_sheet), transforming (convert_to_html), and writing (apply_changes). A minor gap is the lack of a tool for creating new files from scratch, but agents can work around this by modifying parsed data.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-google-sheets

    xing5
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol server that integrates with Google Drive and Google Sheets, enabling users to create, read, update, and manage spreadsheets through natural language commands.
    992
    MIT

  • chatExcel

    Lillard01
    A
    license
    Not graded
    quality
    F
    maintenance
    A Model Context Protocol server for intelligent Excel processing and data analysis, offering tools for reading, validating, executing code, and generating interactive visualizations with Excel files.
    228
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yuqie6/MCP-Sheet-Parser-cot'

If you have feedback or need assistance with the MCP directory API, please join our Discord server