Labsco
contactakagrawal logo

Excel Analyser MCP

★ 4

from contactakagrawal

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

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#payments#documents#devops#git#finance#security

Excel Analyser MCP

MCP Badge npm version npm downloads License MCP Server

A Node.js MCP server for reading and analyzing Excel (.xlsx), CSV (.csv), and JSON (.json) files. Supports multiple 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.

What's New in v2.1.0

  • 🚀 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

What's New in v2.0.0

  • New query_json Tool: 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.

Features

  • Multi-Transport Support: Choose between stdio (npm), HTTP streamable, or SSE transports
  • Read Excel/CSV/JSON files and 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.

MCP Tools

1. read_excel

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.

Parameters:

  • 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.

Returns:

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

Example Request:

Copy & paste — that's it
{
  "filePath": "./your_data.csv",
  "columns": ["description", "category"]
}

2. get_chunk

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

Parameters:

  • 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

Returns:

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

Example Request:

Copy & paste — that's it
{
  "filePath": "./your_data.csv",
  "columns": ["description"],
  "start": 0,
  "limit": 1000
}

Example Response:

Copy & paste — that's it
{
  "chunk": [
    { "description": "Customer cannot login..." },
    { "description": "Payment failed for order..." }
    // ... up to 1000 rows
  ],
  "start": 0,
  "limit": 1000,
  "totalRows": 58635
}

3. read_json

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.

Parameters:

  • 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.

Returns:

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

Example Request:

Copy & paste — that's it
{
  "filePath": "./employees.json",
  "fields": ["name", "department", "salary"]
}

Example Response (large file):

Copy & paste — that's it
{
  "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."
  }
}

4. query_json

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.

Parameters:

  • 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 be contains, equals, startsWith, or endsWith.
    • value (string): The value to match against.

Returns:

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

Example Request:

Copy & paste — that's it
{
  "filePath": "/path/to/your/large_dataset.json",
  "query": {
    "field": "trading_symbol",
    "operator": "contains",
    "value": "TITAN"
  }
}

Example Response:

Copy & paste — that's it
{
  "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."
}

5. get_json_chunk

Description: Fetches a specific chunk of entries from a JSON file. This tool is designed for iterative 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.

Parameters:

  • 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

Returns:

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

Example Request:

Copy & paste — that's it
{
  "filePath": "./large_dataset.json",
  "fields": ["id", "name", "status"],
  "start": 0,
  "limit": 1000
}

Example Response:

Copy & paste — that's it
{
  "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
}

How to Choose the Right JSON Tool

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

  • To explore a new JSON file:

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

  • To find specific data:

    • Use query_json. It's the fastest and most memory-efficient way to search for entries that match a specific condition (e.g., find all users where status is active).

  • To process every entry:

    • Use get_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 the start parameter, until you have processed all totalEntries.

📚 Documentation

Additional documentation is available in the docs/ directory:

  • docs/DEPLOYMENT.md - Complete deployment guide for Railway and other cloud platforms
  • docs/URL_SUPPORT.md - Guide for adding URL support to handle cloud-based file access

Notes

  • Supported file types: .xlsx, .csv, and .json files
  • JSON file requirements: Must contain an array of objects
  • Excel files: Only the first sheet is used by default in chunked operations
  • Automatic pagination: JSON files with >1000 entries automatically use pagination
  • Chunk sizes: Default 1000 for optimal performance, configurable per request
  • Error handling: Comprehensive error messages for file not found, invalid formats, etc.

Testing

The project includes test files for both Excel/CSV and JSON functionality in the tests/ directory:

  • tests/test-readExcelFile.js - Test Excel/CSV reading functionality
  • tests/test-readJsonFile.js - Test JSON reading functionality
  • tests/test-http-transport.js - Test HTTP transport connectivity
  • tests/test-deployment.js - Test deployed server functionality
  • tests/test-data.json - Sample JSON file for testing
  • tests/dummy_excel_file.xlsx - Sample Excel file for testing

To run tests:

Copy & paste — that's it
# Test file processing
npm test                    # Excel/CSV test
npm run test-json          # JSON test
npm run test-all           # All file processing tests

# Test HTTP transport (requires server running)
npm run start:http         # Terminal 1: Start HTTP server
npm run test-http          # Terminal 2: Test HTTP connectivity

# Test deployed server
npm run test-deployment https://your-deployed-url.com

Feedback & Support

We value your feedback and are committed to improving Excel Analyser MCP. Here are several ways you can reach out:

🐛 Found a Bug?

  • GitHub Issues: Report bugs here
  • Please include:
    • Steps to reproduce the issue
    • Expected vs actual behavior
    • File type and size (if applicable)
    • Error messages or logs

💡 Feature Requests & Enhancements

📝 General Feedback

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for more information on how to:

  • Submit pull requests
  • Report issues
  • Suggest improvements
  • Help with documentation

⭐ Show Your Support

If you find this project helpful, please consider:

  • Giving it a ⭐ star on GitHub
  • Sharing it with others who might benefit
  • Contributing to the codebase

License

ISC