AI导哈

Excel SQL查询工具

一个允许用户通过自然语言查询Excel和CSV文件的工具，Claude自动生成并执行SQL查询。

  • by ivan-loh
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 ivan-loh/mcp-excel

使用说明

mcp-server-excel-sql 可以翻译为“MCP服务器-Excel-SQL”或“用于MCP服务器的Excel与SQL（工具/系统）”，具体翻译取决于上下文和该术语的具体用途。如果这是一个软件或系统的名称，那么“用于MCP服务器的Excel与SQL工具/系统”可能是一个更贴切的翻译。如果上下文不明确，使用“MCP服务器-Excel-SQL”作为通用翻译也是可以接受的

让Claude使用SQL查询您的Excel和CSV文件——无需SQL知识。用简单的英语提问，Claude会自动编写并执行查询。

它的功能/作用

其工作原理如下：

  1. 将服务器指向您的Excel/CSV文件
  2. 用通俗易懂的英语向克劳德提问
  3. 克劳德自动编写SQL查询语句
  4. 立即从您的数据中获取答案

能力：

  • 每个Excel表格和CSV文件都变成一个可查询的SQL表
  • 跨多个文件和格式（xlsx、xls、csv、tsv）合并数据
  • 使用YAML转换规则清理杂乱数据
  • 为支持并发访问的团队部署
  • 支持复杂查询（聚合函数、窗口函数、公共表表达式（CTEs））

你应该使用这个吗？

如果您符合以下条件，将非常合适：

  • 处理小于100MB的Excel文件
  • 无需SQL知识即可获取数据洞察
  • 需要合并多个电子表格
  • 使用AI助手（Claude为你编写SQL）
  • 在构建ETL管道之前进行原型设计

如果您有以下情况，则这不是合适的工具：

  • 文件超过100MB（请使用数据库导入功能）
  • 需要修改Excel文件（只读模式）
  • 需要公式/宏/VBA（仅值）
  • 构建生产数据仓库（仅限原型设计）

安装

安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

就是这样。无需安装任何软件包 uvx 按需运行服务器。

立即尝试

git clone https://github.com/ivan-loh/mcp-excel.git
cd mcp-excel
python examples/finance/create_finance_examples.py
uvx --from mcp-server-excel-sql mcp-excel --path examples/finance

快速入门

Claude Desktop（可译为“Claude桌面版”或保持原样，根据上下文决定是否需要具体翻译）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "excel": {
      "command": "uvx",
      "args": [
        "--from", "mcp-server-excel-sql", "mcp-excel",
        "--path", "/path/to/excel/files/"
      ]
    }
  }
}

更新路径并重启 Claude 桌面应用。

命令行测试

# Test with your files
uvx --from mcp-server-excel-sql mcp-excel --path /path/to/excel/files

# With auto-refresh
uvx --from mcp-server-excel-sql mcp-excel --path /path/to/files --watch

常见使用场景

  • 财务分析 - 预算与实际对比、应收账款账龄、收入趋势
  • 销售报告 - 市场区域业绩、产品分析、客户细分
  • 运营；操作；业务活动 - 库存对账、供应商比较、项目跟踪
  • 数据探索 - 快速SQL访问、数据质量测试、分析原型设计

可用工具

  • 工具列表表（或工具表列表） - 列出所有表和视图及其文件路径和行数
  • 获取模式的工具 - 显示表或视图的列名和类型
  • 工具查询 - 执行只读SQL查询（连接、聚合、公共表表达式）
  • 刷新工具 - 文件更改后重新加载数据（使用 --watch 时自动进行）
  • 创建视图工具 - 创建持久化的SQL视图，使其在重启后仍然存在
  • 工具下落视图 - 删除视图及其存储

理解表名

表的名称为： <alias>.<filename>.<sheet> （小写，已清理）

示例： 文件 /data/sales/Q1-2024.xlsx 表格 Summary → sales.q12024.summary

重要提示： 在SQL中始终引用表名：

SELECT * FROM "sales.q12024.summary"  -- Correct

系统视图

  • <alias>.__files - 文件清单（路径、工作表数量、行数、修改时间）
  • <alias>.__tables - 表目录（名称、源文件、工作表、行数）

持久视图

创建可重复使用的SQL视图，并将其存储在磁盘上，以便在服务器重启时自动恢复。

示例：

CREATE VIEW high_value_sales AS
SELECT * FROM "sales.data.summary" WHERE amount > 1000

用于过滤、聚合或多表连接。使用（某种工具或方法）进行管理 tool_create_view()， tool_drop_view()，以及 tool_list_tables()。

数据转换

使用YAML转换规则清理杂乱的Excel文件：

能力：

  • 跳过表头/页脚行，合并多行表头
  • 使用正则表达式或列条件过滤行
  • 重命名列，设置数据类型（日期、小数）
  • 将数据从宽格式转换为长格式，指定单元格范围
  • 从多表工作表中提取表格

用法：

uvx --from mcp-server-excel-sql mcp-excel --path /data --overrides config.yaml

见 examples/finance/finance_overrides.yaml 以获取完整的配置示例。

自动检测功能

自动处理复杂的Excel文件，无需手动配置。

它检测的内容：

  • 合并的单元格，隐藏的行/列
  • 欧洲数字格式（1.234,56 → 小数）
  • 单张纸上多表格
  • 表头行，元数据行

启用：

messy_report.xlsx:
  sheet_overrides:
    "Report":
      auto_detect: true

用途： 合并的单元格标题、隐藏的列、欧洲格式、多表单页、复杂布局。

局限性： 仅支持.xlsx和.xlsm文件。有关高级选项，请参阅DEVELOPMENT.md。

CLI 选项

uvx --from mcp-server-excel-sql mcp-excel [OPTIONS]

选项：

  • --path - 包含Excel文件的目录（默认：当前目录）
  • --overrides - 用于转换的YAML配置文件
  • --watch - 文件更改时自动刷新
  • --transport - 通信模式： stdio， streamable-http， sse （默认：stdio）
  • --host - HTTP/SSE 的主机（默认：127.0.0.1）
  • --port - HTTP/SSE 端口（默认：8000）
  • --require-auth 启用API密钥认证（使用MCP_EXCEL_API_KEY环境变量）

附加文件

多用户部署、安全与开发： 见 DEVELOPMENT.md 翻译为中文是：“开发说明.md” 或 “开发文档.md”（具体翻译可能根据上下文有所调整，但基本意思是关于开发的说明或文档文件） for: （可翻译为“对于”、“为了”、“给”等，具体根据上下文确定）

  • 带身份验证的多用户设置
  • 安全模型与实施
  • 架构与设计决策
  • 性能特性
  • 测试与开发工作流程

示例： 见 示例/README.md 为金融和CNC数据集提供详细的查询示例。

许可证

麻省理工学院（MIT）

相关 MCP