使用说明

项目简介

FastExcel MCP Server 是一个基于 Model Context Protocol (MCP) 构建的 Java 后端服务器，旨在为大型语言模型 (LLM) 客户端提供高效、安全的 Excel 文件数据访问能力。通过标准化的 MCP 协议，该服务器允许 LLM 客户端以工具调用的方式，便捷地读取和利用 Excel 文件中的信息，从而扩展 LLM 在数据处理和分析方面的应用场景。

主要功能点

Excel 文件读取: 支持读取 XLSX, XLS, CSV 格式的 Excel 文件，包括表头和数据行。
工作区限制: 仅允许操作预先配置的工作区目录下的 Excel 文件，保障数据访问的安全性。
多 Sheet 支持: 支持读取 Excel 文件中的多个 Sheet，并允许指定 Sheet 名称进行操作。
自定义表头行: 允许用户指定表头所在的行号，灵活适应不同格式的 Excel 文件。
数据行数统计: 快速获取 Excel 文件中数据行的总数（排除表头行）。
性能缓存: 内置性能缓存机制，加速重复数据访问，提升响应速度。

安装步骤

环境准备: 确保已安装 JDK 17+ GraalVM 和 Maven 3.9.6+。
代码构建: 下载或克隆仓库代码后，在项目根目录下执行 Maven 命令进行打包：
```
mvn clean package -DskipTests=true
```
构建成功后，将在 'target' 目录下生成 'fastexcel-mcp-server-0.0.1-SNAPSHOT.jar' 文件。

服务器配置

MCP 服务器需要配置在 MCP 客户端（例如 Claude Desktop）的配置文件中。以下是一个 'claude_desktop_config.json' 的配置示例，用于配置 FastExcel MCP Server：

{
  "mcpServers": {
    "fastexcel-mcp-server": {  // 服务器名称，可自定义
      "command": "java",      // 启动命令，这里使用 java
      "args": [                // 命令参数
        "-jar",
        "<YOUR_PATH>/fastexcel-mcp-server-0.0.1-SNAPSHOT.jar" //  替换为您的 jar 文件实际路径
      ],
      "env": {                // 环境变量配置
        "MCP_WORKSPACES": "<YOUR_MULTIPLE_WORKSPACES_SEPARATED_BY_COMMAS>", // 必须配置，允许访问的工作区路径，多个路径用逗号分隔，例如 "/path/to/workspace1,/path/to/workspace2"
        "CACHE_INITIAL_CAPACITY": "[OPTIONAL] <MINIMUM_TOTAL_SIZE_FOR_THE_INTERNAL_DATA_STRUCTURES> <DEFAULT: 100>", // 可选配置，缓存初始容量，根据需求调整
        "CACHE_MAXIMUM_SIZE": "[OPTIONAL] <MAXIMUM_NUMBER_OF_ENTRIES_THE_CACHE_MAY_CONTAIN> <DEFAULT: 1000>",     // 可选配置，缓存最大条目数，根据需求调整
        "CACHE_EXPIRE_AFTER_WRITE": "[OPTIONAL] <LENGTH_OF_TIME_AFTER_AN_ENTRY_IS_CREATED_THAT_IT_SHOULD_BE_AUTOMATICALLY_REMOVED> <DEFAULT: 35s>" // 可选配置，缓存过期时间，单位秒，根据需求调整
      }
    }
  }
}

配置说明:

'mcpServers': 配置 MCP 服务器的顶级 JSON 对象。
'fastexcel-mcp-server': 您为该服务器定义的名称，在客户端中引用时使用。
'command': 启动服务器的命令，通常为 'java'。
'args': 传递给 'command' 的参数列表。
- '"-jar"': 指定以 JAR 包方式运行。
- '"<YOUR_PATH>/fastexcel-mcp-server-0.0.1-SNAPSHOT.jar"': 请务必替换为实际的 JAR 文件路径。
'env': 环境变量配置。
- 'MCP_WORKSPACES': 必须配置。 指定服务器允许访问的 Excel 文件所在的工作区目录。可以配置多个工作区路径，用逗号分隔。请根据您的实际文件存储位置进行配置。
- 'CACHE_INITIAL_CAPACITY', 'CACHE_MAXIMUM_SIZE', 'CACHE_EXPIRE_AFTER_WRITE': 可选配置。 用于调整服务器缓存性能，一般情况下使用默认值即可。如有性能需求，可根据注释说明进行调整。

基本使用方法

配置完成后，MCP 客户端（如 Claude Desktop）即可通过以下工具名称调用 FastExcel MCP Server 提供的功能：

'get_total_rows_number': 获取 Excel 文件数据行总数。
'get_sheet_names': 获取 Excel 文件所有 Sheet 名称。
'read_head_spec': 读取 Excel 文件表头信息。
'read_rows_spec': 读取 Excel 文件数据行内容（关联表头）。
'cache_clear': 清空服务器缓存。
'test_cache_available': 测试文件缓存是否可用。

调用示例 (以 'read_rows_spec' 工具为例):

LLM 客户端在需要读取 Excel 数据时，可以指示模型调用 'read_rows_spec' 工具，并提供以下参数：

'excelPath': Excel 文件路径（相对于配置的工作区目录）。
'headRowNumber': 表头行号。
'readRowNumbers' (可选): 要读取的数据行数。
'sheetName' (可选): Sheet 名称。

服务器将返回 JSON 格式的数据，包含 Excel 文件的数据行内容，并已关联表头信息，方便 LLM 进行后续处理和分析。

关键词