mcp-excel
mcp-excel-server is a project based on the Spring AI MCP framework. Its main function is to provide large language model (LLM) with the ability to read and write local Excel files with the help of MCP protocol.
Installation
Run this command in your terminal to add the MCP server to Claude Code.
Run in terminal:
Command
claude mcp add --transport stdio bigcoder84-mcp-excel-server java -Dspring.ai.mcp.server.stdio=true -Dspring.main.web-application-type=none -Dfile.encoding=UTF-8 -jar {your_path}/mcp-excel-server-0.0.1-SNAPSHOT.jarHow to use
mcp-excel-server 提供一个基于 MCP 协议的接口，允许大语言模型（LLM）通过本地 Excel 文件进行读取和写入操作。该服务在 MIT/Java Spring 环境中运行，LLM 客户端通过相应的 MCP 接入点发起对本地 Excel 的读取、解析与数据写入请求，并将结果以结构化的 JSON 形式返回。要使用它，先启动打包后的 jar，然后在 MCP 客户端配置中添加一个 stdio 类型的服务器，端点将会为 LLM 提供对本地 Excel 的能力扩展。该服务支持读取 .xlsx/.xls 文件的内容并将其以 JSON 返回，同时也能把 JSON 数据写入到指定的 Excel 文件中，方便在对话中进行动态数据处理与持久化。
要对接的工具/能力包括：读取 Excel 文件（返回 JSON 结构化数据）、写入 Excel 文件（将 JSON 数据写入指定工作表/单元格）、与支持 MCP 的 LLM 客户端（如 Claude、Cursor、Cherry Studio 等）无缝集成。通过 MCP 协议，LLM 能像使用本地工具一样调用此服务实现对本地数据的动态交互与操作。
How to install
安装步骤（基于 Java/Maven 构建的 MCP 服务）:
- 安装前提
- 已安装 JDK 17 或以上
- 已安装 Maven
- Git（可选）
- 获取源码或构建产物
- 使用 Maven 打包： mvn clean package -Dmaven.test.skip=true 这会生成一个 mcp-excel-server-0.0.1-SNAPSHOT.jar（位于 target 目录）
- 配置运行参数
- 使用示例配置将 jar 路径替换为实际路径，例如： { "mcpServers": { "AUM5itYnoMcxPiU2vFa3Z": { "name": "Excel操作", "type": "stdio", "description": "", "isActive": true, "command": "java", "args": [ "-Dspring.ai.mcp.server.stdio=true", "-Dspring.main.web-application-type=none", "-Dfile.encoding=UTF-8", "-jar", "/path/to/mcp-excel-server-0.0.1-SNAPSHOT.jar" ] } } }
- 启动服务
- 直接用配置启动（依赖你使用的 MCP 客户端工具的方式），确保 jar 路径正确。
- 如果你有自定义路径，请将 {your_path} 替换为实际路径。
- 验证运行
- 通过日志确认服务器已成功就绪，测试对本地 Excel 的读取和写入操作。
Additional notes
注意事项与常见问题:
- 确保 Java 版本为 17 及以上，否则可能出现兼容性问题。
- 打包时跳过测试可提升打包速度：-Dmaven.test.skip=true
- 读取 Excel 时，返回的 JSON 会包含工作表名称、单元格范围及单元格值等信息，便于在 LLM 中进一步处理。
- 写入时，请确保目标文件路径存在且有写权限，避免因权限导致写入失败。
- 在生产环境中，可通过环境变量/系统属性对 Spring 配置进行覆盖，例如开启日志、调整并发等。
