Excel Analyser MCP

Read and analyze Excel (.xlsx) and CSV (.csv) files with scalable, chunked, and column-specific data access, ideal for large datasets.

A Node.js MCP server for reading and analyzing Excel (.xlsx), CSV (.csv), and JSON (.json) files. Supportsmultiple transport protocols(stdio, HTTP, SSE) and designed for scalable, chunked, and column/field-specific data access, making it ideal for AI agents and automation workflows that need to process large datasets efficiently.

Excel Analyser MCP supports multiple transport protocols:stdio(npm/CLI),HTTP streamable, andSSE.

⚡ Ready-to-Use HTTP Server (Recommended)

The fastest way to get started! Use our deployed server without any installation:

MCP Client Configuration (HTTP - Ready to Use):

{ "mcpServers": { "Excel Analyser MCP": { "type": "http", "url": "https://web-production-64851.up.railway.app/mcp" } } }

🎉That's it!No installation required. Start analyzing files immediately.

📝 Example Usage Prompt (HTTP - Use Cloud URLs):

Please analyze the Excel file at https://github.com/contactakagrawal/excel-analyser-mcp/raw/main/tests/dummy_excel_file.xlsx and show me the first few rows and column names.

⚠️ Important for HTTP:Usecloud URLs(GitHub raw, Google Drive public links, etc.) since the server runs remotely and cannot access your local files.

Perfect for MCP clients like Claude Desktop, Cursor, and other CLI-based integrations.

{ "mcpServers": { "Excel Analyser MCP": { "command": "npx", "args": ["-y", "excel-analyser-mcp"] } } }

📝 Example Usage Prompt (Stdio - Use Local Paths):

Please analyze the Excel file at /Users/john/Documents/sales_data.xlsx and show me the first few rows and column names.

⚠️ Important for Stdio:Useabsolute local file pathssince the server runs on your machine and can access your local files directly.

Ideal for web applications, REST API integrations, and serverless deployments.

# Default: runs on http://localhost:8080/mcp npx excel-analyser-mcp streamableHttp # Custom port and endpoint npx excel-analyser-mcp streamableHttp 3000 /excel-mcp

{ "mcpServers": { "Excel Analyser MCP": { "type": "http", "url": "http://localhost:8080/mcp" } } }

📝 Example Usage Prompt (Self-hosted HTTP - Use Local or Cloud URLs):

Please analyze the Excel file at /Users/john/Documents/sales_data.xlsx and show me the first few rows and column names.

⚠️ Important for Self-hosted HTTP:You can uselocal absolute pathsorcloud URLssince your server can access both local files and remote URLs.

For real-time streaming applications (deprecated but still supported).

# Default: runs on http://localhost:8080/sse npx excel-analyser-mcp sse # Custom port and endpoint npx excel-analyser-mcp sse 3000 /excel-sse

{ "mcpServers": { "Excel Analyser MCP": { "type": "sse", "url": "http://localhost:8080/sse" } } }

npm run start # Default stdio transport npm run start:stdio # Explicit stdio transport npm run start:http # HTTP transport on port 8080 npm run start:sse # SSE transport on port 8080

- 🚀 Multi-Transport Support: Now supports stdio (npm), HTTP streamable, and SSE transports for maximum flexibility
- 🔗 HTTP Transport: Perfect for web applications and REST API integrations
- 📡 SSE Transport: Real-time streaming capabilities for advanced use cases
- ⚙️ Easy Configuration: Simple command-line arguments to choose your preferred transport

- Newquery_jsonTool: A powerful new tool for efficiently searching large JSON files based on field values.
- Efficient Streaming: All JSON tools (read_json,query_json,get_json_chunk) have been re-architected to use streaming. This means they can process gigabyte-sized files with minimal memory usage, preventing crashes and ensuring scalability.

- Multi-Transport Support: Choose between stdio (npm), HTTP streamable, or SSE transports
- Read Excel/CSV/JSON filesand output all or selected columns/fields as JSON
- Efficient Streaming: Handle multi-gigabyte JSON files with constant, low memory usage.
- Powerful JSON Querying: Quickly search and filter large JSON files without loading the entire file into memory.
- Chunked Access: Process large files iteratively by fetching data in configurable chunks.
- Column/Field filtering: Extract only the columns or fields you need.
- MCP server integration: Expose tools for AI agents and automation.

npm install yarn install # or your preferred package manager

Or configure your MCP agent to launch this file with Node.js and --stdio.

Description:Reads an Excel or CSV file and returns a preview (first 100 rows) and metadata for large files, or the full data for small files.

- filePath(string, required): Path to the Excel or CSV file on disk (.xlsx or .csv)
- columns(array of strings, optional): Columns to include in the output. If not specified, all columns are included.

- For large files:{ preview: [...], totalRows, columns, message }
- For small files: Full data as an array

{ "filePath": "./your_data.csv", "columns": ["description", "category"] }

Description:Fetches a chunk of rows from a CSV or Excel file, with optional column filtering. Useful for processing large files in batches.

- filePath(string, required): Path to the Excel or CSV file on disk (.xlsx or .csv)
- columns(array of strings, optional): Columns to include in the output
- start(integer, optional, default 0): Row index to start from (0-based)
- limit(integer, optional, default 1000): Number of rows to return in the chunk

- { chunk: [...], start, limit, totalRows }

{ "filePath": "./your_data.csv", "columns": ["description"], "start": 0, "limit": 1000 }

{ "chunk": [ { "description": "Customer cannot login..." }, { "description": "Payment failed for order..." } // ... up to 1000 rows ], "start": 0, "limit": 1000, "totalRows": 58635 }

Description:Efficiently reads a large JSON file to provide a quick preview (first 100 entries) and metadata without loading the entire file into memory. This is the recommended first step for analyzing a new JSON file.

- filePath(string, required): Path to the JSON file on disk (.json)
- fields(array of strings, optional): Fields to include in the output. If not specified, all fields are included.

- For large files (>1000 entries):{ preview: [...], totalEntries, fields, message }
- For small files: Full data as an array

{ "filePath": "./employees.json", "fields": ["name", "department", "salary"] }

{ "JSON": { "preview": [ { "name": "John Doe", "department": "Engineering", "salary": 75000 }, { "name": "Jane Smith", "department": "Marketing", "salary": 65000 } // ... up to 100 entries ], "totalEntries": 15000, "fields": ["id", "name", "email", "age", "department", "salary"], "message": "Data is too large to return in one response. Use get_json_chunk for paginated access or query_json to search." } }

Description:Performs a fast, memory-efficient search on a large JSON file. It streams the file and returns all entries that match the specified query, up to a limit of 1000 results. This is the ideal tool for finding specific data within a large dataset.

- filePath(string, required): Path to the JSON file on disk (.json).
- query(object, required): The query to execute on the JSON data.

- field(string): The field to query (e.g., 'trading_symbol').
- operator(enum): The query operator. Can becontains,equals,startsWith, orendsWith.
- value(string): The value to match against.

- { matches: [...], matchCount, totalEntriesScanned, message }

{ "filePath": "/path/to/your/large_dataset.json", "query": { "field": "trading_symbol", "operator": "contains", "value": "TITAN" } }

{ "matches": [ { "instrument_key": "NSE_EQ|INE280A01028", "trading_symbol": "TITAN" }, { "instrument_key": "NSE_EQ|INE280A01029", "trading_symbol": "TITANBEES" } ], "matchCount": 2, "totalEntriesScanned": 2500000, "message": "Query returned 2 matching entries." }

Description:Fetches a specific chunk of entries from a JSON file. This tool is designed foriterative analysis, where you need to process every entry in the file sequentially, one chunk at a time. It uses efficient streaming to access the requested chunk without re-reading the whole file.

- filePath(string, required): Path to the JSON file on disk (.json)
- fields(array of strings, optional): Fields to include in the output
- start(integer, optional, default 0): Entry index to start from (0-based)
- limit(integer, optional, default 1000): Number of entries to return in the chunk

- { chunk: [...], start, limit, totalEntries }

{ "filePath": "./large_dataset.json", "fields": ["id", "name", "status"], "start": 0, "limit": 1000 }

{ "chunk": [ { "id": 1, "name": "John Doe", "status": "active" }, { "id": 2, "name": "Jane Smith", "status": "inactive" } // ... up to 1000 entries ], "start": 0, "limit": 1000, "totalEntries": 15000 }

Use this guide to select the most efficient tool for your task:

- 1st:Useread_json. It will give you the total number of entries, all available fields, and a preview of the first 100 entries.

- Usequery_json. It's the fastest and most memory-efficient way to search for entries that match a specific condition (e.g., find all users wherestatusisactive).

- Useget_json_chunk. This is for when you need to perform an action on every single entry in the file, such as categorizing support tickets or performing a complex calculation. Call it in a loop, incrementing thestartparameter, until you have processed alltotalEntries.

- Configure your AI agent (e.g., Cursor AI, Copilot) to connect to this MCP server.
- Useread_excelorread_jsonfor a quick preview and metadata.
- Useget_chunkorget_json_chunkto iterate through large files in batches for scalable analysis.
- JSON files with more than 1000 entries automatically use pagination for optimal performance.

Here's an example of how you can use this MCP server with an AI agent to analyze files.

Important:The MCP server requiresabsolute file pathsfor security and reliability reasons.

Scenario:You want to get a summary ofdummy_excel_file.xlsx.

You:Can you analyze the file at/home/john/documents/dummy_excel_file.xlsxand give me the column names and the first few rows?

The agent would make a tool call similar to this:

{ "tool_name": "read_excel", "parameters": { "filePath": "/home/john/documents/dummy_excel_file.xlsx" } }

If the file is large, the server will return a preview:

{ "preview": [ { "ID": 1, "Name": "John Doe", "Sales": 1500 }, { "ID": 2, "Name": "Jane Smith", "Sales": 2200 } ], "totalRows": 10500, "columns": ["ID", "Name", "Sales"], "message": "File is large. Returning a preview of the first 100 rows." }

Scenario:You want to find all stocks with "TITAN" in their trading symbol from a very large JSON file.

You:Can you find all entries in/data/NSE.jsonwhere thetrading_symbolcontainsTITAN?

{ "tool_name": "query_json", "parameters": { "filePath": "/data/NSE.json", "query": { "field": "trading_symbol", "operator": "contains", "value": "TITAN" } } }

{ "matches": [ { "instrument_key": "NSE_EQ|INE280A01028", "trading_symbol": "TITAN" } ], "matchCount": 1, "totalEntriesScanned": 2500000, "message": "Query returned 1 matching entries." }

Scenario:You want to analyze a large JSON dataset of employee records, chunk by chunk.

You:Can you analyze the employee data in/home/john/data/employees.jsonand show me the first chunk?

2. AI Agent uses theget_json_chunktool:

{ "tool_name": "get_json_chunk", "parameters": { "filePath": "/home/john/data/employees.json", "start": 0, "limit": 1000 } }

{ "chunk": [ { "id": 1, "name": "John Doe", "status": "active" } ], "start": 0, "limit": 1000, "totalEntries": 15000 }

Deploy your MCP server to the internet so others can use it via HTTP transport!
- Fork/clonethis repository
- Connect to Railway:railway.app→ New Project → Deploy from GitHub
- Access your server:https://your-app.railway.app/mcp