Excel Reader MCP

🚀 MCP Excel File Reader

A Model Context Protocol (MCP) server for reading Excel files with automatic chunking and pagination. Built with SheetJS and TypeScript, this tool helps you efficiently handle large Excel files by automatically breaking them into manageable chunks.

✨ Features

• 📊 Supports reading Excel files in .xlsx and .xls formats.
• 🔄 Automatically chunks large files for processing.
• 📑 Allows worksheet selection and row pagination.
• 📅 Handles date formats correctly.
• ⚡ Optimized for large files.
• 🛡️ Robust error handling and validation.

📦 Installation

Install via Smithery

Automatically install the Excel Reader for Claude Desktop through Smithery:

npx -y @smithery/cli install @ArchimedesCrypto/excel-reader-mcp-chunked --client claude

Use as an MCP Server

1. Install globally:

npm install -g @archimdescrypto/excel-reader

2. Add to your MCP settings file (usually located at ~/.config/claude/settings.json or similar):

{
  "mcpServers": {
    "excel-reader": {
      "command": "excel-reader",
      "env": {}
    }
  }
}

For Development

1. Clone the repository:

git clone https://github.com/ArchimdesCrypto/mcp-excel-reader.git
cd mcp-excel-reader

2. Install dependencies:

npm install

3. Start the development server:

npm start

💻 Usage Examples

Interface Definition

Request Parameters

interface ReadExcelRequest {
  file: File; // The Excel file to be read
  sheetName?: string; // Optional: Specify the worksheet name to read
  headers?: boolean; // Optional: Whether to include header rows
}

Response Format

interface ReadExcelResponse {
  data: any[][]; // A two-dimensional array containing data
  headers?: string[]; // Optional: An array containing header rows
  error?: string; // Optional: Error information (if any)
}

Basic Usage

import { readExcel } from '@archimdescrypto/excel-reader';

const file = document.getElementById('fileInput') as HTMLInputElement;
const result = await readExcel({
  file: file.files[0],
  headers: true,
});

if (result.error) {
  console.error('An error occurred while reading the file:', result.error);
} else {
  console.log('Data has been successfully read:', result.data);
  if (result.headers) {
    console.log('Header rows:', result.headers);
  }
}

📚 Documentation

Extended Features

The MCP Excel Reader is built on the powerful SheetJS library and supports the following advanced features:

• Formula Handling: Read and calculate formulas in cells directly.
• Cell Styles: Preserve and manipulate cell format information (e.g., font, color, etc.).
• Data Validation: Define and check data validation rules for cells.
• Worksheet Protection: Enable or disable edit protection for worksheets.

🤝 Contribution Guidelines

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Submit a pull request.

📄 License

This project is licensed under the MIT License. Please refer to the LICENSE file for details.

🙏 Acknowledgments

• Built with the powerful SheetJS.
• Part of the Model Context Protocol ecosystem.