Excel MCP Server

A comprehensive Model Context Protocol (MCP) server for reading, writing, and analyzing Excel files. Built by Hatch Ltd for seamless integration with AI assistants.

Features

• Read Excel Files: Extract data from Excel files with support for specific sheets and cell ranges
• Write Excel Files: Create new Excel files or modify existing ones
• Sheet Management: List sheets, get detailed information about Excel files
• Formula Support: Option to include formulas instead of computed values
• Style Support: Extract cell styling information when needed
• Robust Error Handling: Clear error messages and validation

Installation

npm install @hatch/excel-mcp-server

Usage

As an MCP Server

Add to your MCP configuration:

{
  "servers": {
    "excel": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hatch/excel-mcp-server"]
    }
  }
}

Direct Usage

npx @hatch/excel-mcp-server

Available Tools

read_excel_file

Read data from an Excel file with optional sheet and range specification.

Parameters:

• filePath (required): Absolute path to the Excel file
• sheetName (optional): Name of the sheet to read (defaults to first sheet)
• range (optional): Cell range to read (e.g., "A1:C10")
• includeFormulas (optional): Include formulas instead of computed values
• includeStyles (optional): Include cell styling information

write_excel_file

Write data to an Excel file.

Parameters:

• filePath (required): Absolute path to the Excel file
• sheetName (required): Name of the sheet to write to
• data (required): Array of arrays representing the data to write
• range (optional): Starting cell (defaults to "A1")
• createSheet (optional): Create the sheet if it does not exist (default: true)

list_excel_sheets

List all sheet names in an Excel file.

Parameters:

• filePath (required): Absolute path to the Excel file

get_excel_info

Get detailed information about an Excel file including sheets, dimensions, and metadata.

Parameters:

• filePath (required): Absolute path to the Excel file

create_excel_file

Create a new Excel file with specified data.

Parameters:

• filePath (required): Absolute path for the new Excel file
• sheets (required): Array of sheet objects to create

Example Usage

Reading an Excel File

{
  "tool": "read_excel_file",
  "arguments": {
    "filePath": "/path/to/your/file.xlsx",
    "sheetName": "Sheet1",
    "range": "A1:D10"
  }
}

Creating a New Excel File

{
  "tool": "create_excel_file",
  "arguments": {
    "filePath": "/path/to/new/file.xlsx",
    "sheets": [
      {
        "name": "Data",
        "data": [
          ["Name", "Age", "City"],
          ["John", 30, "New York"],
          ["Jane", 25, "Los Angeles"]
        ]
      }
    ]
  }
}

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

Requirements

• Node.js >= 18.0.0
• Excel files in .xlsx format

License

MIT License - see LICENSE file for details.

Support

For issues and support, please visit our GitHub repository.