Fastexcel MCP Server

🚀 FastExcel MCP Server

A Java-based Model Context Protocol (MCP) server for Excel operations with standardized header and column relationship mapping.

🚀 Quick Start

If you are using Claude Desktop, add the MCP server information to the configuration file:

{
  "mcpServers": [
    {
      "name": "FastExcelMCP",
      "executable": "/path/to/javacExecutable",
      "options": ["-Dsome.option=value"],
      "jvmArgs": [],
      "workingDir": "."
    }
  ]
}

✨ Features

• Read the headers and data rows of Excel files (XLSX, XLS, CSV).
• Validate whether the input path is within the configured workspace.
• Support multiple worksheets and custom header rows.
• Get the total number of data rows (excluding the header row).
• Built-in performance cache for faster repeated access.

⚠️ Important Note

The server only allows operations within the workspace directories configured via env: MCP_WORKSPACES.

📚 Documentation

API

Tools

get_total_rows_number (with cache support)

Get the total number of data rows (excluding the header row) in an Excel file.

• Input:
  • excelPath (string): The absolute or relative path to the Excel file.
  • headRowNumber (integer): The row number where the header is located (1-based index).
  • sheetName (string, optional): The name of the worksheet to read. If empty, the first worksheet is used by default.
• Output:
  • Returns the total number of data rows as an integer.

get_sheet_names (with cache support)

Get the names and indices of all worksheets in an Excel file.

• Input:
  • excelPath (string): The absolute or relative path to the Excel file.
• Output:
  • Returns a list of objects containing the worksheet numbers and names.

read_head_spec (with cache support)

Parse and return the header information in an Excel file.

• Input:
  • excelPath (string): The absolute or relative path to the Excel file.
  • headRowNumber (integer): The row number where the header is located (1-based index).
  • sheetName (string, optional): The name of the worksheet to read. If empty, the first worksheet is used by default.
• Output:
  • Returns a list of objects with column indices and headers in order.

read_rows_spec (with cache support)

Parse and return the data row information associated with the headers.

• Input:
  • excelPath (string): The absolute or relative path to the Excel file.
  • headRowNumber (integer): The row number where the header is located (1-based index).
  • readRowNumbers (integer, optional): The number of data rows to read (excluding the header). If empty, all data rows are read.
  • sheetName (string, optional): The name of the worksheet to read. If empty, the first worksheet is used by default.
• Output:
  • Returns a list containing the row data and their corresponding headers.

cache_clear

Clear all cached Excel file data in memory.

• Output:
  • Returns true when the cache is successfully cleared.

test_cache_available

Test whether a specified Excel file exists in the cache.

• Output:
  • Returns a boolean indicating whether the file is in the cache.

📦 Installation

The project requires JDK 17+ and Maven 3.9.6+. Build it using the following command:

mvn clean install

📄 License

This software is licensed under the Apache License 2.0.