Excel MCP Server

Excel MCP Server

简体中文 | English

基于 Model Context Protocol（MCP）的 Excel 文件处理服务，提供读取、写入和分析 Excel 文件的功能。

功能

• 📖 读取 Excel 文件

  • 获取工作表列表
  • 读取指定工作表数据
  • 读取所有工作表数据

• ✍️ 写入 Excel 文件

  • 创建新的 Excel 文件
  • 写入指定工作表
  • 支持多个工作表

• 🔍 分析 Excel 结构

  • 分析工作表结构
  • 将结构导出到新文件

• 💾 缓存管理

  • 自动缓存文件内容
  • 定时清理缓存
  • 手动清除缓存

• 📝 日志管理

  • 自动记录操作日志
  • 定期清理日志

安装

通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 excel-mcp-server：

npx -y @smithery/cli install @zhiwei5576/excel-mcp-server --client claude

手动安装

通过 NPM 安装 在 MCP 服务配置中添加以下配置，即可自动安装 excel-mcp-server。

Windows 平台：

{
  "mcpServers": {
    "excel": {
        "command": "cmd",
        "args": ["/c", "npx", "--yes", "@zhiweixu/excel-mcp-server"],
        "env": {
            "LOG_PATH": "[set an accessible absolute path]",
            "CACHE_MAX_AGE": "1",
            "CACHE_CLEANUP_INTERVAL": "4",
            "LOG_RETENTION_DAYS": "7",
            "LOG_CLEANUP_INTERVAL": "24"
        }
    }
}

其他平台：

{
  "mcpServers": {
    "excel": {
        "command": "npx",
        "args": ["--yes", "@zhiweixu/excel-mcp-server"],
        "env": {
            "LOG_PATH": "[set an accessible absolute path]",
            "CACHE_MAX_AGE": "1",
            "CACHE_CLEANUP_INTERVAL": "4",
            "LOG_RETENTION_DAYS": "7",
            "LOG_CLEANUP_INTERVAL": "24"
        }
    }
}

注意：LOG_PATH 为可选项。如果未设置，日志将存储在应用根目录下的 logs 文件夹中。其他参数均为可选项。

API 工具

结构工具

1. analyzeExcelStructure

   • 功能：以 JSON 格式获取 Excel 文件结构，包括工作表列表和列标题
   • 参数：
     • fileAbsolutePath：Excel 文件的绝对路径
     • headerRows：标题行数（默认值：1）

2. exportExcelStructure

   • 功能：将 Excel 文件结构（工作表和标题）导出到新的 Excel 模板文件
   • 参数：
     • sourceFilePath：源 Excel 文件路径
     • targetFilePath：目标 Excel 文件路径
     • headerRows：标题行数（默认值：1）

读取工具

1. readSheetNames

   • 功能：获取 Excel 文件中的所有工作表名称
   • 参数：
     • fileAbsolutePath：Excel 文件的绝对路径

2. readDataBySheetName

   • 功能：获取 Excel 文件中指定工作表的数据
   • 参数：
     • fileAbsolutePath：Excel 文件的绝对路径
     • sheetName：要读取的工作表名称
     • headerRow：标题行号（默认值：1）
     • dataStartRow：数据起始行号（默认值：2）

3. readSheetData

   • 功能：获取 Excel 文件中所有工作表的数据
   • 参数：
     • fileAbsolutePath：Excel 文件的绝对路径
     • headerRow：标题行号（默认值：1）
     • dataStartRow：数据起始行号（默认值：2）

写入工具

1. writeDataBySheetName

   • 功能：向 Excel 文件中的指定工作表写入数据（如果工作表已存在，则覆盖）
   • 参数：
     • fileAbsolutePath：Excel 文件的绝对路径
     • sheetName：要写入的工作表名称
     • data：要写入的数据数组

2. writeSheetData

   • 功能：使用提供的数据创建新的 Excel 文件
   • 参数：
     • fileAbsolutePath：新 Excel 文件的绝对路径
     • data：包含多个工作表数据的对象

缓存工具

1. clearFileCache
   • 功能：清除指定 Excel 文件的缓存数据
   • 参数：
     • fileAbsolutePath：要从缓存中清除的 Excel 文件的绝对路径

配置

环境变量

• LOG_PATH：日志文件存储路径

  • 可选
  • 默认值：应用程序根目录下的 'logs' 文件夹

• CACHE_MAX_AGE：缓存过期时间（小时）

  • 可选
  • 默认值：1

• CACHE_CLEANUP_INTERVAL：缓存清理间隔（小时）

  • 可选
  • 默认值：4

• LOG_RETENTION_DAYS：日志保留天数

  • 可选
  • 默认值：7

• LOG_CLEANUP_INTERVAL：日志清理间隔（小时）

  • 可选
  • 默认值：24

默认配置

• 缓存配置

  • 缓存过期时间：1 小时
  • 缓存清理间隔：4 小时

• 日志配置

  • 日志保留天数：7 天
  • 清理间隔：24 小时

依赖项

• @modelcontextprotocol/sdk: ^1.7.0
• xlsx: ^0.18.5
• typescript: ^5.8.2

开发依赖项

• @types/node: ^22.13.10
• nodemon: ^3.1.9
• ts-node: ^10.9.2

许可证

本项目采用 MIT 许可证。这意味着您可以：

• 将本软件用于商业或非商业用途

• 修改源代码

• 分发原始或修改后的代码 要求：

• 保留原始版权声明

• 不得因使用本软件向作者追究责任 如需了解许可证的详细信息，请参阅 LICENSE 文件。