Fastexcel MCP Server

🚀 FastExcel MCP Server

A Java-based MCP (Model Context Protocol) server designed for handling Excel operations and supporting standard header-column relationships.

✨ Features

• Read headers and data rows from Excel files (XLSX, XLS, CSV).
• Validate if the input path conforms to the configured workspace.
• Support multiple sheets and custom header rows.
• Retrieve the total number of data rows (excluding headers) in an Excel file.
• Incorporate a built-in performance cache for faster repeated access.

⚠️ Important Note

This server only allows operations within the working directories configured in env: MCP_WORKSPACES.

📚 Documentation

API - Tools

• get_total_rows_number (with cache support)

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

• get_sheet_names (with cache support)

  • Retrieve all worksheet names and their indices in an Excel file.
  • Input:
    • excelPath (string): Absolute or relative path to the Excel file.
  • Returns a list of objects containing worksheet numbers and names.

• read_head_spec (with cache support)

  • Parse and return the header information in an Excel file.
  • Input:
    • excelPath (string): Absolute or relative path to the Excel file.
    • headRowNumber (integer): Row number where the header is located (1-based index).
    • sheetName (string, optional): Name of the worksheet to read. If empty, the first worksheet is used by default.
  • Returns an ordered list of column index and title objects.

• read_rows_spec (with cache support)

  • Parse and return the data row information associated with the header.
  • Input:
    • excelPath (string): Absolute or relative path to the Excel file.
    • headRowNumber (integer): Row number where the header is located (1-based index).
    • readRowNumbers (integer, optional): Number of data rows to read (excluding the header). If null, all data rows are read.
    • sheetName (string, optional): Name of the worksheet to read. If empty, the first worksheet is used by default.
  • Returns a list of objects containing row data and their header links.

• cache_clear

  • Clear all cached Excel file data from memory.
  • Returns true upon successful clearance.

• test_cache_available

  • Check if a specified Excel file is available in the cache.
  • Input:
    • excelPath (string): Absolute or relative path to the Excel file.
  • Returns a boolean indicating whether the file is in the cache.

💻 Usage Examples

Usage with Claude Desktop

To use this server in Claude Desktop, add the following content to the configuration file claude_desktop_config.json:

{
  "fastExcelMcpServer": {
    "enabled": true,
    "config": {
      "mcpEndpoint": "http://localhost:8080", // Endpoint address of the MCP service
      "workSpaceRoot": "/path/to/workspace", // Root directory of the workspace
      "cacheExpiration": 3600, // Cache expiration time (in seconds)
      "maxCacheSize": 1000 // Maximum number of cached files
    }
  }
}

📦 Installation

Environment Requirements

• JDK 8 or higher
• Maven 3.6 or higher

Build Command

To use this server in your project, execute the following Maven command:

mvn clean install

📄 License

This server is licensed under the Apache License 2.0.