内容
# mcp-server-excel-sql
[](https://pypi.org/project/mcp-server-excel-sql/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://github.com/ivan-loh/mcp-excel/actions)
让 Claude 查询您的 Excel 和 CSV 文件，使用 SQL - 无需 SQL 知识。直接用中文提问，Claude 自动编写并执行查询。
## 功能介绍
**工作原理：**
1. 将服务器指向您的 Excel/CSV 文件
2. 用中文直接向 Claude 提问
3. Claude 自动编写 SQL 查询
4. 从数据中获取即时答案
**功能特点：**
- 每个 Excel 工作表和 CSV 文件都成为一个可查询的 SQL 表
- 跨多个文件和格式（xlsx, xls, csv, tsv）连接数据
- 使用 YAML 转换规则清理凌乱的数据
- 为团队部署并支持并发访问
- 支持复杂查询（聚合、窗口函数、CTE）
## 是否适合您？
**非常适合：**
- 处理小于 100MB 的 Excel 文件
- 无需 SQL 知识即可获取数据洞察
- 需要连接多个电子表格
- 使用 AI 助手（Claude 为您编写 SQL）
- 在构建 ETL 管道之前进行原型设计
**不适合：**
- 文件大于 100MB（请改用数据库导入）
- 需要修改 Excel 文件（只读）
- 需要公式/宏/VBA（仅限值）
- 构建生产数据仓库（仅限原型设计）
## 安装
**安装 uv：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
就这样。不需要安装软件包 - `uvx` 按需运行服务器。
## 立即试用
```bash
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 桌面版
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"excel": {
"command": "uvx",
"args": [
"--from", "mcp-server-excel-sql", "mcp-excel",
"--path", "/path/to/excel/files/"
]
}
}
}
```
更新路径并重启 Claude 桌面版。
### 命令行测试
```bash
# 使用您的文件进行测试
uvx --from mcp-server-excel-sql mcp-excel --path /path/to/excel/files
# 自动刷新
uvx --from mcp-server-excel-sql mcp-excel --path /path/to/files --watch
```
## 常见用例
- **财务分析** - 预算 vs 实际，AR 老化，收入趋势
- **销售报告** - 地区绩效，产品分析，客户细分
- **运营** - 库存核对，供应商比较，项目跟踪
- **数据探索** - 快速 SQL 访问，数据质量测试，分析原型设计
## 可用工具
- **tool_list_tables** - 列出所有表和视图及其文件路径和行数
- **tool_get_schema** - 显示表或视图的列名和类型
- **tool_query** - 执行只读 SQL 查询（连接，聚合，CTE）
- **tool_refresh** - 在文件更改后重新加载数据（自动刷新）
- **tool_create_view** - 创建持久的 SQL 视图，重启后仍然存在
- **tool_drop_view** - 删除视图及其存储
## 表名理解
表名格式：`<alias>.<filename>.<sheet>`（小写，清理）
**示例：** 文件 `/data/sales/Q1-2024.xlsx` 工作表 `Summary` → `sales.q12024.summary`
**重要：** 在 SQL 中始终引用表名：
```sql
SELECT * FROM "sales.q12024.summary" -- 正确
```
## 系统视图
- **`<alias>.__files`** - 文件清单（路径，工作表数量，行数，修改时间）
- **`<alias>.__tables`** - 表目录（名称，源文件，工作表，行数）
## 持久视图
创建存储在磁盘上的可重用 SQL 视图，服务器重启后自动恢复。
**示例：**
```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 文件：
**功能特点：**
- 跳过标题/页脚行，合并多行标题
- 使用正则表达式或列条件过滤行
- 重命名列，设置数据类型（日期，小数）
- 将宽格式转换为长格式，指定单元格范围
- 从多表工作表中提取表格
**用法：**
```bash
uvx --from mcp-server-excel-sql mcp-excel --path /data --overrides config.yaml
```
参见 `examples/finance/finance_overrides.yaml` 获取完整的配置示例。
## 自动检测功能
自动处理复杂的 Excel 文件，无需手动配置。
**检测内容：**
- 合并单元格，隐藏行/列
- 欧洲数字格式（1.234,56 → 小数）
- 单个工作表上的多个表格
- 标题行，元数据行
**启用：**
```yaml
messy_report.xlsx:
sheet_overrides:
"Report":
auto_detect: true
```
**用于：** 合并单元格标题，隐藏列，欧洲格式，多表工作表，复杂布局。
**限制：** 仅限 `.xlsx` 和 `.xlsm`。参见 DEVELOPMENT.md 获取高级选项。
## CLI 选项
```bash
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](DEVELOPMENT.md) 获取：
- 多用户设置和身份验证
- 安全模型和执行
- 架构和设计决策
- 性能特征
- 测试和开发工作流
**示例：**
参见 [examples/README.md](examples/) 获取财务和 CNC 数据集的详细查询示例。
## 许可证
MIT
