Excel MCP Server

基于 Model Context Protocol (MCP) 的 Excel 文件处理服务，智能体能够通过标准化接口操作 Excel 文件。

目前仅支持多 Excel / 多 Sheet 的统一内存容器、文件合并拆分等能力。

✨ 功能特性

• 多 Excel / 多 Sheet 统一容器 —— 惰性加载 + LRU 缓存，重复访问不重复读盘

• 灵活的文件扫描 —— 支持扩展名过滤（.xlsx / .xls）、文件名通配、递归扫描

• 原子操作 —— 合并、按列拆分、按 sheet 导出、多文件导出

• 一步到位工具 —— excel_merge_from_paths 单次调用完成"加载 → 合并 → 导出"

• 智能命名 —— sheet 名 / 文件名自动处理重名、非法字符、超长截断（含 WARNING 日志）

• 显式 Schema —— 每个工具都提供完整的 inputSchema，LLM 选工具、传参更准确

• 中文友好 —— 错误提示、日志、文档均为中文

Related MCP server: Excel MCP Server

📁 目录结构

excel-mcp-server/
├── excel_mcp_server/                    # 主包
│   ├── __init__.py                      # 包声明
│   ├── _shared.py                       # 共享工具（Excel 读写、JSON 序列化）
│   ├── excel_bundle.py                  # ExcelBundle：多文件/多 sheet 内存容器
│   ├── bundle_registry.py               # ExcelBundleRegistry：进程级注册表
│   ├── server.py                        # MCP 服务器入口
│   └── tools/                           # 工具模块
│       ├── __init__.py
│       └── document.py                  # DocumentTools：文件级操作工具集
├── excel_mcp.log                        # 运行日志（首次运行自动生成）
└── README.md

🚀 快速开始

1. 环境要求

• Python ≥ 3.10（用到 match / case 语法）

2. 启动服务器

方式 A：模块方式（推荐，从包外目录启动）

cd excel-mcp-server
python -m excel_mcp_server.server

方式 B：脚本方式（从包目录里启动）

cd excel-mcp-server/excel_mcp_server
python server.py

⚠️ 导入路径说明：server.py 里用的是 from bundle_registry import REGISTRY（平级导入），需要在 excel_mcp_server/ 目录内运行；document.py 里用的是 from excel_mcp_server.bundle_registry import ...（绝对导入），需要从包外目录运行。两者取其一，保持一致性即可。如果不确定，用方式 A。

启动后它会在 stdio 上等待 MCP 客户端消息，直接运行没有输出是正常的。

🧰 MCP 工具清单

共 13 个工具，分为 4 类：

生命周期（4）

探查（5）

合并 / 拆分（3）

导出（2）