excel-reader

The Excel Reader MCP server lets AI agents read and paginate large Excel files (.xlsx, .xls) by automatically chunking data into manageable pieces. Built on SheetJS and TypeScript, it supports selecting a specific sheet, paging through rows, and returning structured chunk metadata including row ranges and column headers. When integrated with an MCP-enabled assistant (like Claude or other MCP clients), you can invoke the read_excel tool to fetch data from a given file path with optional sheet and pagination parameters. This enables efficient handling of large datasets without loading the entire file at once. Use the tool to request a chunk-by-chunk traversal, or to fetch a particular subset of rows from a sheet, with the response indicating whether more chunks remain and how to request the next one.

Available capabilities include:

• Automatic chunking with a default chunk size for large files
• Sheet selection by name (defaulting to the first sheet)
• Row pagination through startRow and maxRows parameters
• Metadata detailing total sheets, current sheet, and per-chunk data including column headers and data rows
• Robust error handling for missing files, incorrect formats, or malformed Excel content

Prerequisites:

• Node.js and npm installed on your system
• Access to a shell/terminal

Option A: Install via Smithery (recommended for Claude Desktop integration)

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

Option B: Install as a standalone MCP server (Node.js package)

1. Install dependencies and build locally

git clone https://github.com/ArchimdesCrypto/mcp-excel-reader.git
cd mcp-excel-reader
npm install
npm run build

2. Install globally (if you plan to expose as an MCP server)

npm install -g @archimdescrypto/excel-reader

3. Add the MCP server configuration to your MCP settings (e.g., in ~/.config/claude/settings.json)

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

Option C: Development workflow (local testing)

1. Clone the repository and install dependencies

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

2. Build for development

npm run build

3. Run the server locally if provided with a start script (check package.json for available commands)

npm run start

Notes:

• The MCP server is designed to read Excel files in chunks to support large datasets without loading the entire file into memory.
• Default chunk size is tuned for performance; adjust via configuration in the client tool if supported by your MCP runtime.
• Ensure the filePath you pass to read_excel points to a accessible path on the host where the MCP server runs.
• Sheet selection defaults to the first sheet if not provided.
• If you encounter issues with file parsing, verify that the Excel file is valid and not corrupted; SheetJS support for advanced features (formulas, formatting, data validations) can be enabled via the extended options described in the README, if your implementation exposes them.
• Environment variables can be added under env to control behavior (e.g., chunk size, date handling). Use descriptive keys like CHUNK_SIZE or DATE_AS_NUMBER as appropriate for your deployment.