使用说明

项目简介

Excel MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端应用，专门用于处理 Excel 文件。它通过标准化的 MCP 协议，向 LLM 客户端提供读取、写入、分析和管理 Excel 文件的能力，使得 LLM 应用可以方便地与 Excel 数据进行交互。

主要功能点

读取 Excel 文件：
- 获取 Excel 文件中的所有工作表名称。
- 读取指定工作表或所有工作表的数据，支持自定义表头行和数据起始行。
写入 Excel 文件：
- 创建新的 Excel 文件，或在现有文件中写入数据。
- 支持写入数据到指定工作表，或创建包含多个工作表的新 Excel 文件。
分析 Excel 结构：
- 分析 Excel 文件的结构，包括工作表列表和每列的表头信息。
- 导出 Excel 文件结构到新的 Excel 模板文件。
缓存管理：
- 自动缓存已读取的 Excel 文件内容，提高重复访问性能。
- 定时清理过期缓存，保持缓存有效性。
- 支持手动清除指定文件的缓存。
日志管理：
- 自动记录服务器操作日志，方便问题追踪和审计。
- 定期清理过期的日志文件，节省存储空间。

安装步骤

前提条件：确保您的环境中已安装 Node.js 和 npm (Node 包管理器)。

通过 Smithery 安装 (推荐 Claude Desktop 用户)：如果您使用 Claude Desktop 等 MCP 客户端，可以通过 Smithery 快速安装：

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

手动安装 (NPM)：对于其他 MCP 客户端或自定义部署，您无需手动安装 npm 包。只需在 MCP 客户端中配置 Excel MCP Server 的启动命令即可。

服务器配置

MCP 客户端需要配置以下 JSON 格式信息来启动和连接 Excel MCP Server。以下是通用的配置示例，您可以根据您的 MCP 客户端进行配置：

{
  "mcpServers": {
    "excel": { //  服务名称，在客户端配置中用于引用此服务器
      "command": "npx", //  启动服务器的命令，这里使用 npx 运行 npm 包
      "args": ["--yes", "@zhiweixu/excel-mcp-server"] //  命令参数，--yes 表示自动确认执行 npm 包
    }
  }
}

Windows 平台配置示例：

{
  "mcpServers": {
    "excel": {
      "command": "cmd", // Windows 平台需要使用 cmd /c 来执行 npx 命令
      "args": ["/c", "npx", "--yes", "@zhiweixu/excel-mcp-server"]
    }
  }
}

可选环境变量 'LOG_PATH': 您可以设置 'LOG_PATH' 环境变量来指定日志文件的存储路径。如果未设置，日志文件将默认存储在服务器程序根目录下的 'logs' 文件夹中。

基本使用方法

启动服务器： MCP 客户端根据上述配置启动 Excel MCP Server。服务器将在后台运行，并通过 Stdio (标准输入输出) 与客户端通信。
客户端调用工具：客户端通过 MCP 协议向 Excel MCP Server 发送 JSON-RPC 请求，调用预定义的工具来执行 Excel 文件操作。例如：
- 使用 'readSheetNames' 工具获取工作表列表。
- 使用 'readDataBySheetName' 工具读取指定工作表的数据。
- 使用 'writeDataBySheetName' 工具向指定工作表写入数据。
- 使用 'analyzeExcelStructure' 工具分析 Excel 文件结构。
- 使用 'clearFileCache' 工具清除文件缓存。
每个工具的具体参数和使用方法，请参考仓库 README.md 文件中的 API Tools 章节。客户端需要根据工具定义传递正确的参数，例如文件路径 ('fileAbsolutePath')、工作表名称 ('sheetName')、表头行号 ('headerRow')、数据起始行号 ('dataStartRow') 以及要写入的数据等。
获取结果：服务器执行工具后，将通过 JSON-RPC 响应返回结果给客户端。结果通常以 JSON 字符串形式包含在 'content' 字段中，客户端需要解析 JSON 字符串以获取具体的操作结果或数据。

关键词