AI导哈

表格管理服务器

一个全面的表格管理服务器，支持Excel和CSV文件的创建、读取、写入、格式化和图表生成等高级功能。

  • by d-ang356
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 d-ang356/spreadsheet_mcp_server

使用说明

电子表格MCP服务器

一个全面的模型上下文协议（MCP）服务器，用于管理Excel和CSV电子表格，具有高级功能，包括公式、格式、图表和窗格冻结。

特性

核心业务

  • 文件管理：创建、读取、写入、删除、重命名和列出电子表格文件
  • 工作表操作：在工作簿中创建、重命名和管理多个工作表
  • 数据操作：读取、写入、追加行和更新单个单元格
  • 公式支持：设置和检索具有跨表引用的Excel公式

高级功能

  • 单元格格式：粗体、斜体、字体大小和背景颜色
  • 范围格式化：一次格式化多个单元格
  • 列/行格式：设置列宽和行高
  • 冻结窗格：冻结行和/或列，以便于数据导航
  • 图表：从数据范围创建条形图和饼图

支持格式

  • Excel（.xlsx）：全功能支持，包括公式、格式和图表
  • CSV（.CSV）：基本读/写操作

安装

先决条件

  • Docker已安装并正在运行
  • Claude Desktop或MCP兼容客户端

设置

  1. 克隆或创建项目目录:
mkdir spreadsheet-mcp-server
cd spreadsheet-mcp-server

  1. 创建所需文件:

    • spreadsheet_server.py （主服务器代码）
    • requirements.txt （Python依赖关系）
    • Dockerfile （容器配置）
    • catalog.yaml （MCP目录配置）

  2. 安装Python依赖项 （用于本地测试）：

pip install -r requirements.txt
  1. 构建Docker镜像:
docker build -t spreadsheet-mcp-server:latest .
  1. 配置Claude桌面:

添加到您的MCP设置中：（Claude/Claude_desktop_config.json-->应在Windows上的AppData/Roaming下的Windows用户名目录下）

{
  "mcpServers": {
   "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
		"-i",
        "--rm",
		"--init",
        "-v",
        "/var/run/docker.sock:/var/run/docker.sock",
        "-v",
        "/Users/[YOUR USERNAME]/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/spreadsheet-mcp.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    },
    "spreadsheet": {
      "command": "docker",
      "args": [
        "run",
		"-i",
        "--rm",
		"--init",
        "-v",
       "C:\\Users\\[YOUR USERNAME]\\spreadsheets:/app/spreadsheets",
    "-v",
    "C:\\Users\\[YOUR USERNAME]\\Downloads:/imports",
        "spreadsheet-mcp-server:latest"
      ]
    }
  }
}

替换 [YOUR USERNAME] 上面代码中提到的任何地方都使用您的Windows用户名，或者用实际的Linux路径替换整行。 确保C:\Users\[您的用户名]\电子表格存在！

  1. 将这些添加到有关MCP的Docker Desktop配置目录中:

首先编辑.docker/mcp/register.yaml（路径应该在Windows的用户名目录下） 在现有代码下以类似格式添加：

spreadsheet:
    ref: ""

然后复制并粘贴文件 spreadsheet-mcp.yaml 到.docker/mcp/catalogs（同样在Windows上的同一位置）

使用示例

创建电子表格

# Create a new Excel file with headers
await create_spreadsheet(
    filename="sales.xlsx",
    sheet_name="Q1",
    headers=["Date", "Product", "Amount"]
)

写入数据

# Write data to a specific sheet (creates sheet if it doesn't exist)
await write_spreadsheet(
    filename="sales.xlsx",
    sheet="Q1",
    data=[
        ["Date", "Product", "Amount"],
        ["2024-01-01", "Widget", 100],
        ["2024-01-02", "Gadget", 150]
    ]
)

使用公式

# Set a formula in a cell
await set_formula(
    filename="sales.xlsx",
    sheet="Summary",
    cell="B2",
    formula="=Q1!C2"
)

# Cross-sheet reference
await set_formula(
    filename="sales.xlsx",
    sheet="Data1",
    cell="E2",
    formula="=Data2!A2"
)

格式化

# Format header row with green background
await format_cells(
    filename="sales.xlsx",
    sheet="Q1",
    cell_range="A1:E1",
    bold=True,
    bg_color="#00FF00"
)

# Format a single cell
await set_cell_format(
    filename="sales.xlsx",
    sheet="Q1",
    cell="A1",
    bold=True,
    italic=True,
    bg_color="FFFF0000"  # Red with full opacity
)

列和行大小

# Set column width
await set_column_format(
    filename="sales.xlsx",
    sheet="Q1",
    column="A",
    width=20
)

# Set row height
await set_row_format(
    filename="sales.xlsx",
    sheet="Q1",
    row=1,
    height=30
)

冷冻面板

# Freeze top row
await freeze_panes(
    filename="sales.xlsx",
    sheet="Q1",
    cell="A2"
)

# Freeze first column
await freeze_panes(
    filename="sales.xlsx",
    sheet="Q1",
    cell="B1"
)

# Freeze both top row and first column
await freeze_panes(
    filename="sales.xlsx",
    sheet="Q1",
    cell="B2"
)

# Unfreeze panes
await unfreeze_panes(
    filename="sales.xlsx",
    sheet="Q1"
)

创建图表

# Create a bar chart
await create_chart(
    filename="sales.xlsx",
    sheet="Q1",
    chart_type="bar",
    data_range="A1:B10",
    title="Sales by Product"
)

# Create a pie chart
await create_chart(
    filename="sales.xlsx",
    sheet="Q1",
    chart_type="pie",
    data_range="A1:B5",
    title="Market Share"
)

api参考

文件操作

工具 说明 必需参数
list_files 列出所有电子表格文件 pattern （可选）
create_spreadsheet 创建新的电子表格 filename
delete_spreadsheet 删除电子表格 filename
rename_file 重命名文件 old_filename, new_filename

工作表操作

工具 说明 必需参数
rename_sheet 重命名图纸 filename, old_sheet, new_sheet

数据运营

工具 说明 必需参数
read_spreadsheet 读取电子表格数据 filename
write_spreadsheet 将数据写入电子表格 filename, data
append_row 追加一行 filename, row_data
update_cell 更新单个单元格 filename, sheet, cell, value

公式运算

工具 说明 必需参数
set_formula 设置单元格公式 filename, sheet, cell, formula
get_formula 获取单元格公式 filename, sheet, cell

格式化操作

工具 说明 必需参数
format_cells 设置单元格范围格式 filename, sheet, cell_range
set_cell_format 格式化单个单元格 filename, sheet, cell
set_column_format 格式化列 filename, sheet, column
set_row_format 设置行格式 filename, sheet, row

高级功能

工具 说明 必需参数
freeze_panes 冻结窗格 filename, sheet, cell
unfreeze_panes 移除冻结的窗格 filename, sheet
create_chart 创建图表 filename, sheet, chart_type, data_range

颜色格式

颜色可以用两种格式指定：

  1. RGB十六进制 （6个字符）： #00FF00 或 00FF00

    • 自动转换为完全不透明的ARGB

  2. ARGB十六进制 （8个字符）： FF00FF00

    • 前两个字符=alpha（不透明度）： FF =完全不透明
    • 剩余六个=RGB颜色

示例：

  • 绿色： #00FF00 → 转换为 FF00FF00
  • 红色： #FF0000 → 转换为 FFFF0000
  • 半透明蓝色： 8000FF00 （50%不透明度）

目录结构

spreadsheet-mcp-server/
├── spreadsheet_server.py    # Main server code
├── requirements.txt          # Python dependencies
├── Dockerfile               # Docker configuration
├── spreadsheet-mcp.yaml     # MCP catalog
├── README.md               # This file
└── spreadsheets/           # Working directory (created automatically)

故障排除

服务器未出现在Claude Desktop中

  1. 验证Docker镜像是否已构建： docker images | grep spreadsheet-mcp-server
  2. 检查克劳德桌面日志： ~/Library/Logs/Claude/mcp*.log （Mac）或 %APPDATA%\Claude\logs\mcp*.log （Windows）
  3. 确保所有工具 inputSchema 定义于 handle_tools_list()

“颜色必须是aRGB十六进制值”错误

  • 使用 _normalize_color() 辅助功能
  • 确保颜色正确 #RRGGBB 或 AARRGGBB 格式

“工作表不存在”错误

  • 这 write_spreadsheet 和 append_row 方法现在自动创建工作表
  • 更新代码后重建Docker镜像

未创建工作表

  • 确保您正在使用更新的 write_spreadsheet() 包括自动创建工作表
  • 验证工作表名称不包含无效字符

发展

在本地运行测试

# Install dependencies
pip install -r requirements.txt

# Run server in stdio mode
python spreadsheet_server.py

变更后的重建

# Rebuild Docker image
docker build -t spreadsheet-mcp-server:latest .

# Restart Claude Desktop completely (quit and reopen)

版本历史记录

v1.1.0（当前）

  • 添加了冻结/解冻窗格功能
  • 在写入操作中自动创建工作表
  • 颜色归一化（RGB→ ARGB)
  • 图表创建（条形图和饼图）
  • 列和行格式
  • 增强的错误处理

v1.0.0

  • 初始版本
  • 基本CRUD操作
  • 公式支持
  • 单元格格式

许可证

MIT许可证-随意修改和分发。

贡献

欢迎投稿！请确保：

  1. 所有工具都有适当的 inputSchema 定义
  2. 已实施错误处理
  3. Docker镜像构建成功
  4. 使用Claude Desktop测试工具

支持

对于问题或疑问：

  • 检查故障排除部分
  • 查看克劳德桌面日志
  • 验证Docker容器是否正在运行： docker ps | grep spreadsheet

相关 MCP