excel mcp server

简体中文 | English

Excel file processing server based on Model Context Protocol (MCP), providing functionalities for reading, writing, and analyzing Excel files.

Features

• ? Read Excel Files

• Get worksheet list

• Read specific worksheet data

• Read all worksheets data

• ✍️ Write Excel Files

• Create new Excel files

• Write to specific worksheet

• Support multiple worksheets

• ? Analyze Excel Structure

• Analyze worksheet structure

• Export structure to new file

• ? Cache Management

• Automatic file content caching

• Scheduled cache cleanup

• Manual cache clearing

• ? Log Management

• Automatic operation logging
• Periodic log cleanup

Installation

Installing via Smithery

To install excel-mcp-server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @zhiweixu/excel-mcp-server --client claude

Installing Manually

Installing via NPM excel-mcp-server can be automatically installed by adding the following configuration to the MCP servers configuration.

Windows Platform:

{
  "mcpServers": {
    "excel": {
        "command": "cmd",
        "args": ["/c", "npx", "--yes", "@zhiweixu/excel-mcp-server"],
        "env": {
            "LOG_PATH": "[set an accessible absolute path]"
        }
    }
}

Other Platforms:

{
  "mcpServers": {
    "excel": {
        "command": "npx",
        "args": ["--yes", "@zhiweixu/excel-mcp-server"],
        "env": {
            "LOG_PATH": "[set an accessible absolute path]"
        }
    }
}

API Tools

Structure Tools

1. analyzeExcelStructure
2. Function: Get Excel file structure including sheet list and column headers in JSON format

3. Parameters:

   • fileAbsolutePath: Absolute path of the Excel file
   • headerRows: Number of header rows (default: 1)

4. exportExcelStructure

5. Function: Export Excel file structure (sheets and headers) to a new Excel template file
6. Parameters:
   • sourceFilePath: Source Excel file path
   • targetFilePath: Target Excel file path
   • headerRows: Number of header rows (default: 1)

Read Tools

1. readSheetNames
2. Function: Get all sheet names from the Excel file

3. Parameters:

   • fileAbsolutePath: Absolute path of the Excel file

4. readDataBySheetName

5. Function: Get data from a specific sheet in the Excel file

6. Parameters:

   • fileAbsolutePath: Absolute path of the Excel file
   • sheetName: Name of the sheet to read
   • headerRow: Header row number (default: 1)
   • dataStartRow: Data start row number (default: 2)

7. readSheetData

8. Function: Get data from all sheets in the Excel file
9. Parameters:
   • fileAbsolutePath: Absolute path of the Excel file
   • headerRow: Header row number (default: 1)
   • dataStartRow: Data start row number (default: 2)

Write Tools

1. writeDataBySheetName
2. Function: Write data to a specific sheet in the Excel file (overwrites if sheet exists)

3. Parameters:

   • fileAbsolutePath: Absolute path of the Excel file
   • sheetName: Name of the sheet to write
   • data: Array of data to write

4. writeSheetData

5. Function: Create a new Excel file with provided data
6. Parameters:
   • fileAbsolutePath: Absolute path for the new Excel file
   • data: Object containing multiple sheet data

Cache Tools

1. clearFileCache
2. Function: Clear cached data for the specified Excel file
3. Parameters:
   • fileAbsolutePath: Absolute path of the Excel file to clear from cache

Configuration

• Cache Configuration

• Cache expiration time: 1 hour

• Cache cleanup interval: 4 hours

• Log Configuration

• Log retention days: 7 days

• Cleanup interval: 24 hours

Dependencies

• @modelcontextprotocol/sdk: ^1.7.0
• xlsx: ^0.18.5
• typescript: ^5.8.2

Development Dependencies

• @types/node: ^22.13.10
• nodemon: ^3.1.9
• ts-node: ^10.9.2

License

This project is licensed under the MIT License. This means you are free to:

• Use the software for commercial or non-commercial purposes
• Modify the source code

• Distribute original or modified code Requirements:

• Retain the original copyright notice

• No liability can be claimed against the authors for software use For detailed license information,please see the LICENSE file.