Name: 表格数据处理服务
Author: marekrost

使用说明

mcp服务器电子表格

mcp名称：io.github.marekrost/mcp服务器预说明书

数据优先MCP服务器，用于读取和写入电子表格文件(.xlsx, .csv, .ods).

主要特点

多格式 --使用Excel(.xlsx)，CSV(.csv)，以及OpenDocument(.ods)通过统一的工具界面创建文件。
双模式 --单元级工作簿操作和DuckDB驱动的SQL查询引擎，在同一文件上自由交错。
工作簿要点 --工作表、行、列、单元格、搜索。
仅数据 --保留现有格式，但只读取和写入值。
无状态 --每次呼叫都指定 file 和 sheet 明确地；没有句柄或会话。
原子能节省 --写入到临时文件，然后 os.replace() 进入目标路径。
写入时的类型强制 --数字字符串变成数字，其他一切都是文本。
跨表SQL --通过内存中的DuckDB进行JOIN、GROUP BY、聚合、子查询；突变会写回文件。
CSV作为单页工作簿 --CSV文件被视为一个工作簿，其中有一张名为 default.

需求

Python 3.10+

安装

来自PyPI（推荐）

无需本地结账——只需配置您的MCP客户端（见下文）。

来源（用于开发）

git clone https://github.com/marekrost/mcp-server-spreadsheet.git
cd mcp-server-spreadsheet
uv sync

用法

克劳德桌面版

添加到您的 claude_desktop_config.json:

使用PyPI（推荐）：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uvx",
      "args": ["mcp-server-spreadsheet"]
    }
  }
}

使用本地来源：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
    }
  }
}

克劳德代码

添加到您的 .mcp.json:

使用PyPI（推荐）：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uvx",
      "args": ["mcp-server-spreadsheet"]
    }
  }
}

使用本地来源：

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-server-spreadsheet", "main.py"]
    }
  }
}

独立（标准传输）

# PyPI
uvx mcp-server-spreadsheet

# Local source
uv run main.py

限制对目录的文件访问（可选）

集 MCP_SPREADSHEET_ROOT 将所有路径参数限制在单个目录树中。它之外的路径将被拒绝，并向代理返回一个明确的错误。

{
  "mcpServers": {
    "mcp-server-spreadsheet": {
      "command": "uvx",
      "args": ["mcp-server-spreadsheet"],
      "env": { "MCP_SPREADSHEET_ROOT": "/home/me/spreadsheets" }
    }
  }
}

取消设置（默认），允许服务器进程访问的任何路径。

设置注释格式

格式	图纸	公式	类型
`.xlsx`	多重	保留为字符串	原生（int、float、date、bool）
`.ods`	多重	未保留	原生（int、float、date、bool）
`.csv`	单身(`default`)	N/A	负载推断（int、float、text）

表单管理工具(add_sheet, delete_sheet, copy_sheet)引发CSV文件错误。

工具

工作簿操作

工具	说明
`list_workbooks`	列出目录中的所有电子表格文件（非递归）
`create_workbook_file`	创建新的空电子表格文件（按扩展名格式化）
`copy_workbook`	将现有文件复制到新路径

工作表操作

工具	说明
`list_sheets`	列出工作簿中的所有工作表名称
`add_sheet`	添加新工作表（可选名称和职位）
`rename_sheet`	重命名现有图纸
`delete_sheet`	按名称删除工作表
`copy_sheet`	在工作簿中复制工作表（可选新名称和位置）

读取数据

工具	说明
`read_sheet`	将整个工作表读取为行（可选行/列边界）
`read_cell`	读取单个单元格值，例如。 `B3`
`read_range`	读取矩形范围，例如。 `A1:D10`
`get_sheet_dimensions`	获取已使用范围的行数和列数

写入数据

工具	说明
`write_cell`	将值写入单个单元格
`write_range`	从给定单元格开始写一个二维数组
`append_rows`	在最后一行之后追加行
`insert_rows`	在某个位置插入空白或预填行（向下移动行）
`delete_rows`	按索引删除行（向上移动行）
`clear_range`	在不删除行/列的情况下清除范围内的值
`copy_range`	将一块单元格复制到另一个位置（可选地复制到其他工作表）

列操作

工具	说明
`insert_columns`	在某个位置插入空白列
`delete_columns`	按索引删除列

搜索

工具	说明
`search_sheet`	搜索值或正则表达式模式，返回匹配的单元格引用

表模式（SQL）

工具	说明
`describe_table`	检查列名、推断类型、行数和示例值
`sql_query`	执行只读SQL `SELECT` （支持跨表的JOIN、GROUP BY、聚合、子查询）
`sql_execute`	执行 `INSERT INTO`, `UPDATE`，或 `DELETE FROM` --将更改写回文件

SQL示例：

-- Filter and sort
SELECT name, revenue FROM Sales WHERE status = 'Active' ORDER BY revenue DESC LIMIT 20

-- Cross-sheet JOIN
SELECT o.order_id, c.name FROM Orders o JOIN Customers c ON o.customer_id = c.id

-- Aggregate
SELECT department, COUNT(*) AS n, AVG(salary) AS avg FROM Employees GROUP BY department

-- Mutate
UPDATE Sales SET status = 'Closed' WHERE quarter = 'Q1' AND revenue < 1000
DELETE FROM Logs WHERE date < '2024-01-01'

必须引用带空格的图纸名称： SELECT * FROM "Q1 Sales".

表不从第1行开始的表

所有三个SQL工具都接受 header_row 和 data_start_row。每个都可以是 int（适用于每一页）或a {sheet_name: row} 映射（图纸不所列内容将恢复为默认值）。使用 header_row 当列标题生效时在第1行下方，以及 data_start_row 当多余的行（例如单位行）就位时在头部和数据之间。

# Header on row 3, data follows immediately
sql_query(file, 'SELECT * FROM "People"', header_row=3)

# Mixed workbook: People headers at row 3, Orders header at row 1 with a
# units row at row 2.
sql_query(
    file,
    'SELECT * FROM "Orders" o JOIN "People" p ON o.name = p.name',
    header_row={"People": 3, "Orders": 1},
    data_start_row={"Orders": 3},
)

sql_execute 保留上面的行 header_row 当书写变回时。

运行测试

uv sync --group dev
uv run pytest

每种工具都是针对 .xlsx, .csv，以及 .ods 生成到临时目录中的夹具。

公共参数

每个图纸级工具都接受：

参数	必填	说明
`file`	yes	电子表格文件（.xlsx、.csv或.ods）的路径
`sheet`	否	工作表名称。默认为工作簿中的第一页

所有行/列索引均为 1-基单元格引用使用A1表示法(A1, $B$2).