mcp-server-spreadsheet

mcp-server-spreadsheet

mcp-name: io.github.marekrost/mcp-server-spreadsheet

以数据为先的 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

将以下内容添加到 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"]
    }
  }
}

Claude Code

将以下内容添加到 .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"]
    }
  }
}

独立运行（stdio 传输）

# PyPI
uvx mcp-server-spreadsheet

# Local source
uv run main.py

将文件访问限制在某个目录中（可选）

设置 MCP_SPREADSHEET_ROOT，将所有路径参数限制在单个目录树中。超出该目录范围的路径将被拒绝，并向 Agent 返回明确的错误信息。

{
  "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）	不适用	加载时推断（int、float、文本）

对于 CSV 文件，工作表管理工具（add_sheet、delete_sheet、copy_sheet）会报错。

工具

工作簿操作

工具	描述
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。它们可以是整数（应用于每个工作表），也可以是 {sheet_name: row} 映射（未列出的工作表使用默认值）。当列标题位于第 1 行以下时，使用 header_row；当标题与数据之间有额外行（例如单位行）时，使用 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	是	电子表格文件的路径（.xlsx、.csv 或 .ods）
sheet	否	工作表名称。默认为工作簿中的第一个工作表

所有行/列索引均从 1 开始。单元格引用使用 A1 表示法（A1、$B$2）。