📌Overview

Purpose: The Excel MCP Server aims to facilitate seamless reading, writing, and analysis of Excel files using the Model Context Protocol (MCP).

Overview: The Excel MCP Server is a robust framework designed for efficient Excel file processing. It provides a range of functionalities that cater to various Excel operations, making it an ideal solution for users who require data manipulation and analysis within Excel documents.

Key Features:

• Read Excel Files: Users can retrieve worksheet lists and specific data from one or all worksheets, ensuring easy access to needed information.

• Write Excel Files: The framework supports creating new Excel files and writing data to specific worksheets, accommodating multiple worksheets for comprehensive data management.

• Analyze Excel Structure: It allows for analysis of worksheet structures and exporting of those structures to new files, aiding users in understanding and restructuring their data.

• Cache Management: The server includes automatic content caching with scheduled cleanup and options for manual cache management to optimize performance.

• Log Management: Automatic logging of operations is provided along with periodic log cleanup, ensuring efficient tracking and management of server activities.

---

Excel MCP Server

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 @zhiwei5576/excel-mcp-server --client claude

Installing Manually

Windows Platform

{
  "mcpServers": {
    "excel": {
      "command": "cmd",
      "args": ["/c", "npx", "--yes", "@zhiweixu/excel-mcp-server"],
      "env": {
        "LOG_PATH": "[set an accessible absolute path]",
        "CACHE_MAX_AGE": "1",
        "CACHE_CLEANUP_INTERVAL": "4",
        "LOG_RETENTION_DAYS": "7",
        "LOG_CLEANUP_INTERVAL": "24"
      }
    }
  }
}

Other Platforms

{
  "mcpServers": {
    "excel": {
      "command": "npx",
      "args": ["--yes", "@zhiweixu/excel-mcp-server"],
      "env": {
        "LOG_PATH": "[set an accessible absolute path]",
        "CACHE_MAX_AGE": "1",
        "CACHE_CLEANUP_INTERVAL": "4",
        "LOG_RETENTION_DAYS": "7",
        "LOG_CLEANUP_INTERVAL": "24"
      }
    }
  }
}

Note: LOG_PATH is optional. If not set, logs will be stored in the 'logs' folder under the application root directory. Other arguments are optional.

API Tools

Structure Tools

1. analyzeExcelStructure

   • Get Excel file structure including sheet list and column headers in JSON format
   • Parameters:
     • fileAbsolutePath: Absolute path of the Excel file
     • headerRows: Number of header rows (default: 1)

2. exportExcelStructure

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

Read Tools

1. readSheetNames

   • Get all sheet names from the Excel file
   • Parameters:
     • fileAbsolutePath: Absolute path of the Excel file

2. readDataBySheetName

   • Get data from a specific sheet in the Excel file
   • 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)

3. readSheetData

   • Get data from all sheets in the Excel file
   • 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

   • Write data to a specific sheet in the Excel file (overwrites if sheet exists)
   • Parameters:
     • fileAbsolutePath: Absolute path of the Excel file
     • sheetName: Name of the sheet to write
     • data: Array of data to write

2. writeSheetData

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

Cache Tools

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

Configuration

Environment Variables

• LOG_PATH: Log files storage path (Optional, default: 'logs' folder under application root)
• CACHE_MAX_AGE: Cache expiration time in hours (Optional, default: 1)
• CACHE_CLEANUP_INTERVAL: Cache cleanup interval in hours (Optional, default: 4)
• LOG_RETENTION_DAYS: Log retention days (Optional, default: 7)
• LOG_CLEANUP_INTERVAL: Log cleanup interval in hours (Optional, default: 24)

Default Configuration

• Cache:
  • Expiration time: 1 hour
  • Cleanup interval: 4 hours
• Logs:
  • 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. 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.