使用说明

项目简介

FastExcel MCP Server 是一个 Java 应用程序，它实现了 Model Context Protocol (MCP) 协议，旨在为大型语言模型 (LLM) 客户端提供结构化的 Excel 数据访问能力。该服务器允许 LLM 通过标准化的工具调用，安全地读取和操作 Excel 文件，从而扩展 LLM 在数据分析和处理方面的能力。它特别适用于需要处理表格数据并将其作为上下文信息提供给 LLM 的应用场景。

主要功能点

读取 Excel 文件数据: 支持读取 XLSX、XLS 和 CSV 格式的 Excel 文件。
灵活的工作空间配置: 通过环境变量 'MCP_WORKSPACES' 限制服务器可访问的文件目录，增强安全性。
多 Sheet 和自定义表头行支持: 允许指定 Sheet 名称和表头所在的行号，灵活处理不同的 Excel 文件结构。
提供 Excel 数据操作工具:
- 'get_total_rows_number': 获取 Excel 文件中的数据行总数（不包括表头）。
- 'get_sheet_names': 获取 Excel 文件中所有 Sheet 的名称和索引。
- 'read_head_spec': 解析并返回 Excel 文件的表头信息，支持指定表头行和 Sheet。
- 'read_rows_spec': 读取 Excel 文件的数据行，并与表头关联，支持指定读取行数和 Sheet。

安装步骤

安装 JDK 17+ 和 Maven 3.9.6+: 确保您的开发环境中已安装 JDK 17 或更高版本，以及 Maven 3.9.6 或更高版本。
下载或克隆仓库: 从 GitHub 仓库 fastexecl-mcp-server 下载源代码或使用 Git 克隆到本地。
编译项目: 在项目根目录下，打开终端并执行以下 Maven 命令进行编译打包：
```
mvn clean package -DskipTests=true
```
编译成功后，将在 'target' 目录下生成 'fastexecl-mcp-server-0.0.1-SNAPSHOT.jar' 文件。

服务器配置

MCP 服务器需要配置工作空间，以限制其可访问的文件路径，保障安全。您需要在 MCP 客户端的配置文件中指定服务器的启动命令和工作空间。

以下是 Claude Desktop 客户端的 'claude_desktop_config.json' 配置文件示例，展示了如何配置 FastExcel MCP Server：

{
  "mcpServers": {
    "fastexcel": {
      "command": "java",
      "args": [
        "-jar",
        "<YOUR_PATH>/fastexecl-mcp-server-0.0.1-SNAPSHOT.jar"
      ],
      "env": {
        "MCP_WORKSPACES": "<YOUR_MULTIPLE_WORKSPACES_SEPARATED_BY_COMMAS>"
      }
    }
  }
}

配置参数说明:

'"fastexcel"': 服务器名称，您可以自定义。
'"command": "java"': 启动服务器的命令，这里使用 Java 运行时环境。
'"args"': 启动参数列表：
- '"-jar"': 指定运行 JAR 文件。
- '"<YOUR_PATH>/fastexecl-mcp-server-0.0.1-SNAPSHOT.jar"': 请替换为实际的 JAR 文件路径。
'"env"': 环境变量配置：
- '"MCP_WORKSPACES": "<YOUR_MULTIPLE_WORKSPACES_SEPARATED_BY_COMMAS>"': 请替换为您允许服务器访问的工作空间路径。多个工作空间路径用逗号分隔。务必配置此项，以确保服务器只能访问指定目录下的 Excel 文件。

注意: MCP 客户端（例如 Claude Desktop）会读取此配置信息，并使用 'command' 和 'args' 启动 MCP 服务器。'MCP_WORKSPACES' 环境变量用于服务器运行时限制文件访问范围。

基本使用方法

启动 MCP 服务器: 配置好 'claude_desktop_config.json' 后，当 Claude Desktop 客户端需要使用 'fastexcel' 服务器时，会自动根据配置启动 FastExcel MCP Server。您无需手动启动服务器。
在 LLM 中调用工具: 在支持 MCP 协议的 LLM 应用中，您可以使用以下工具来操作 Excel 文件。例如，在提示词中指示 LLM 调用 'get_sheet_names' 工具来获取 Excel 文件的 Sheet 列表，或者使用 'read_rows_spec' 工具读取数据行。

工具列表及调用示例 (在 LLM 提示词中指示 LLM 使用):

get_total_rows_number: 获取 Excel 数据行总数。

{
  "tool_code": "get_total_rows_number",
  "tool_input": {
    "excelPath": "example.xlsx",
    "headRowNumber": 1,
    "sheetName": "Sheet1"
  }
}

get_sheet_names: 获取 Sheet 名称列表。

{
  "tool_code": "get_sheet_names",
  "tool_input": {
    "excelPath": "example.xlsx"
  }
}

read_head_spec: 读取表头信息。

{
  "tool_code": "read_head_spec",
  "tool_input": {
    "excelPath": "example.xlsx",
    "headRowNumber": 1,
    "sheetName": "Sheet1"
  }
}

read_rows_spec: 读取数据行。

{
  "tool_code": "read_rows_spec",
  "tool_input": {
    "excelPath": "example.xlsx",
    "headRowNumber": 1,
    "readRowNumbers": 10,
    "sheetName": "Sheet1"
  }
}

注意: 'excelPath' 参数可以使用绝对路径或相对于工作空间的相对路径。确保 Excel 文件位于您在 'MCP_WORKSPACES' 环境变量中配置的工作空间目录下。

关键词