FastExcel MCP Server

Java server implementing Model Context Protocol (MCP) for Excel operations with standardized header-to-column relationships.

Features

• Read Excel file (XLSX, XLS, CSV) headers and data rows.
• Validate input paths against configured workspaces.
• Support for multiple sheets and custom header rows.
• Retrieve total number of data rows (excluding headers).
• Built-in performance caching for faster repeated access.

Note: The server will only allow operations within directories specified via env: MCP_WORKSPACES.

API

Tools

• get_total_rows_number (with cache support)

  • Get the total number of data rows (excluding the header row) in an Excel file.
  • Inputs:
    • excelPath (string): Absolute or relative path to the Excel file.
    • headRowNumber (integer): Row number (1-based index) where the header is located.
    • sheetName (string, optional): Name of the sheet to read. Defaults to the first sheet if empty.
  • Returns the total count of data rows as an integer.

• get_sheet_names (with cache support)

  • Retrieve all sheet names and their indices from an Excel file.
  • Inputs:
    • excelPath (string): Absolute or relative path to the Excel file.
  • Returns a list of json objects containing sheet number and sheet name.

• read_head_spec (with cache support)

  • Parse and return the header information from an Excel file.
  • Inputs:
    • excelPath (string): Absolute or relative path to the Excel file.
    • headRowNumber (integer): Row number (1-based index) where the header is located.
    • sheetName (string, optional): Name of the sheet to read. Defaults to the first sheet if empty.
  • Returns a sorted list of json objects containing column index and header titles.

• read_rows_spec (with cache support)

  • Parse and return the data rows from an Excel file with header association.
  • Inputs:
    • excelPath (string): Absolute or relative path to the Excel file.
    • headRowNumber (integer): Row number (1-based index) where the header is located.
    • readRowNumbers (integer, optional): Number of data rows to read (excludes header). If null, reads all rows.
    • sheetName (string, optional): Name of the sheet to read. Defaults to the first sheet if empty.
  • Returns a list of json containing row data linked to their headers.

• cache_clear

  • Clear all cached Excel file data from memory.
  • Returns true when cache is cleared successfully.

• test_cache_available

  • Test if the specified Excel file is available in cache.
  • Inputs:
    • excelPath (string): Absolute or relative path to the Excel file.
  • Returns a json object indicating cache status and file MD5 hash:
    • cached: boolean indicating if file is cached
    • result: string containing file MD5 hash information

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

Java

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

Build

Required

• JDK 17+ GraalVM
• Maven 3.9.6+

Java build:

mvn clean package -DskipTests=true

License

This MCP server is licensed under the Apache License 2.0. For more details, please see the LICENSE file in the project repository.

---

If you need further customization or integration details, let me know!