Excel Analyser MCP

Lee y analiza archivos Excel (.xlsx) y CSV (.csv) con acceso escalable, fragmentado y específico por columna, ideal para conjuntos de datos grandes.

GitHub

Prueba este MCPPatrocinado

Documentación

Excel Analyser MCP

Un servidor MCP de Node.js para leer y analizar archivos Excel (.xlsx), CSV (.csv) y JSON (.json). Admite múltiples protocolos de transporte (stdio, HTTP, SSE) y está diseñado para acceso escalable, por fragmentos y específico de columnas/campos, lo que lo hace ideal para agentes de IA y flujos de trabajo de automatización que necesitan procesar grandes conjuntos de datos de manera eficiente.

🚀 Inicio Rápido - Configuración

Excel Analyser MCP admite múltiples protocolos de transporte: stdio (npm/CLI), HTTP streamable y SSE.

⚡ Servidor HTTP Listo para Usar (Recomendado)

¡La forma más rápida de empezar! Usa nuestro servidor desplegado sin necesidad de instalación:

Configuración del Cliente MCP (HTTP - Listo para Usar):

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

🎉 ¡Eso es todo! No se requiere instalación. Comienza a analizar archivos de inmediato.

📝 Ejemplo de Prompt de Uso (HTTP - Usa URLs en la Nube):

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.

⚠️ Importante para HTTP: Usa URLs en la nube (GitHub raw, enlaces públicos de Google Drive, etc.) ya que el servidor se ejecuta de forma remota y no puede acceder a tus archivos locales.

Transporte NPM/Stdio (Autoalojado)

Perfecto para clientes MCP como Claude Desktop, Cursor y otras integraciones basadas en CLI.

Configuración de mcp.json:

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

📝 Ejemplo de Prompt de Uso (Stdio - Usa Rutas Locales):

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

⚠️ Importante para Stdio: Usa rutas de archivo locales absolutas ya que el servidor se ejecuta en tu máquina y puede acceder directamente a tus archivos locales.

Transporte HTTP (Autoalojado)

Ideal para aplicaciones web, integraciones de API REST y despliegues serverless.

Iniciar Servidor HTTP:

# Default: runs on http://localhost:8080/mcp
npx excel-analyser-mcp streamableHttp

# Custom port and endpoint
npx excel-analyser-mcp streamableHttp 3000 /excel-mcp

Configuración del Cliente MCP (HTTP):

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

📝 Ejemplo de Prompt de Uso (HTTP Autoalojado - Usa URLs Locales o en la Nube):

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

⚠️ Importante para HTTP Autoalojado: Puedes usar rutas absolutas locales o URLs en la nube ya que tu servidor puede acceder tanto a archivos locales como a URLs remotas.

Transporte SSE (Autoalojado)

Para aplicaciones de streaming en tiempo real (obsoleto pero aún compatible).

Iniciar Servidor SSE:

# Default: runs on http://localhost:8080/sse
npx excel-analyser-mcp sse

# Custom port and endpoint  
npx excel-analyser-mcp sse 3000 /excel-sse

Configuración del Cliente MCP (SSE):

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

Scripts de Desarrollo (Autoalojado)

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

Novedades en v2.1.0

🚀 Soporte Multi-Transporte: Ahora admite transportes stdio (npm), HTTP streamable y SSE para máxima flexibilidad
🔗 Transporte HTTP: Perfecto para aplicaciones web e integraciones de API REST
📡 Transporte SSE: Capacidades de streaming en tiempo real para casos de uso avanzados
⚙️ Configuración Fácil: Argumentos de línea de comandos simples para elegir tu transporte preferido

Novedades en v2.0.0

Nueva Herramienta query_json: Una poderosa herramienta nueva para buscar eficientemente en archivos JSON grandes según valores de campos.
Streaming Eficiente: Todas las herramientas JSON (read_json, query_json, get_json_chunk) han sido rediseñadas para usar streaming. Esto significa que pueden procesar archivos de tamaño gigabyte con un uso mínimo de memoria, evitando fallos y garantizando escalabilidad.

Características

Soporte Multi-Transporte: Elige entre transportes stdio (npm), HTTP streamable o SSE
Lee archivos Excel/CSV/JSON y genera todas o columnas/campos seleccionados como JSON
Streaming Eficiente: Maneja archivos JSON de varios gigabytes con un uso de memoria constante y bajo.
Consultas JSON Potentes: Busca y filtra rápidamente archivos JSON grandes sin cargar todo el archivo en memoria.
Acceso por Fragmentos: Procesa archivos grandes de forma iterativa obteniendo datos en fragmentos configurables.
Filtrado de Columnas/Campos: Extrae solo las columnas o campos que necesitas.
Integración con servidor MCP: Expone herramientas para agentes de IA y automatización.

Primeros Pasos

Requisitos Previos

Node.js (v18 o superior recomendado)

Instalación

npm install
yarn install # or your preferred package manager

Ejecutar el Servidor MCP

node excel-analyser-mcp.js

O configura tu agente MCP para lanzar este archivo con Node.js y --stdio.

Herramientas MCP

1. `read_excel`

Descripción: Lee un archivo Excel o CSV y devuelve una vista previa (primeras 100 filas) y metadatos para archivos grandes, o los datos completos para archivos pequeños.

Parámetros:

filePath (string, obligatorio): Ruta al archivo Excel o CSV en disco (.xlsx o .csv)
columns (array de strings, opcional): Columnas a incluir en la salida. Si no se especifica, se incluyen todas las columnas.

Devuelve:

Para archivos grandes: { preview: [...], totalRows, columns, message }
Para archivos pequeños: Datos completos como un array

Ejemplo de Solicitud:

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

2. `get_chunk`

Descripción: Obtiene un fragmento de filas de un archivo CSV o Excel, con filtrado de columnas opcional. Útil para procesar archivos grandes en lotes.

Parámetros:

filePath (string, obligatorio): Ruta al archivo Excel o CSV en disco (.xlsx o .csv)
columns (array de strings, opcional): Columnas a incluir en la salida
start (integer, opcional, por defecto 0): Índice de fila desde el que comenzar (basado en 0)
limit (integer, opcional, por defecto 1000): Número de filas a devolver en el fragmento

Devuelve:

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

Ejemplo de Solicitud:

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

Ejemplo de Respuesta:

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

3. `read_json`

Descripción: Lee eficientemente un archivo JSON grande para proporcionar una vista previa rápida (primeras 100 entradas) y metadatos sin cargar todo el archivo en memoria. Este es el primer paso recomendado para analizar un archivo JSON nuevo.

Parámetros:

filePath (string, obligatorio): Ruta al archivo JSON en disco (.json)
fields (array de strings, opcional): Campos a incluir en la salida. Si no se especifica, se incluyen todos los campos.

Devuelve:

Para archivos grandes (>1000 entradas): { preview: [...], totalEntries, fields, message }
Para archivos pequeños: Datos completos como un array

Ejemplo de Solicitud:

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

Ejemplo de Respuesta (archivo grande):

{
  "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`

Descripción: Realiza una búsqueda rápida y eficiente en memoria sobre un archivo JSON grande. Transmite el archivo y devuelve todas las entradas que coinciden con la consulta especificada, hasta un límite de 1000 resultados. Esta es la herramienta ideal para encontrar datos específicos dentro de un conjunto de datos grande.

Parámetros:

filePath (string, obligatorio): Ruta al archivo JSON en disco (.json).
query (object, obligatorio): La consulta a ejecutar sobre los datos JSON.
- field (string): El campo a consultar (p. ej., 'trading_symbol').
- operator (enum): El operador de consulta. Puede ser contains, equals, startsWith o endsWith.
- value (string): El valor con el que comparar.

Devuelve:

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

Ejemplo de Solicitud:

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

Ejemplo de Respuesta:

{
  "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`

Descripción: Obtiene un fragmento específico de entradas de un archivo JSON. Esta herramienta está diseñada para análisis iterativo, donde necesitas procesar cada entrada del archivo secuencialmente, un fragmento a la vez. Utiliza streaming eficiente para acceder al fragmento solicitado sin volver a leer todo el archivo.

Parámetros:

filePath (string, obligatorio): Ruta al archivo JSON en disco (.json)
fields (array de strings, opcional): Campos a incluir en la salida
start (integer, opcional, por defecto 0): Índice de entrada desde el que comenzar (basado en 0)
limit (integer, opcional, por defecto 1000): Número de entradas a devolver en el fragmento

Devuelve:

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

Ejemplo de Solicitud:

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

Ejemplo de Respuesta:

{
  "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
}

Cómo Elegir la Herramienta JSON Correcta

Usa esta guía para seleccionar la herramienta más eficiente para tu tarea:

Para explorar un archivo JSON nuevo:
- 1º: Usa read_json. Te dará el número total de entradas, todos los campos disponibles y una vista previa de las primeras 100 entradas.
Para encontrar datos específicos:
- Usa query_json. Es la forma más rápida y eficiente en memoria de buscar entradas que coincidan con una condición específica (p. ej., encontrar todos los usuarios donde status es active).
Para procesar cada entrada:
- Usa get_json_chunk. Esto es para cuando necesitas realizar una acción en cada entrada del archivo, como categorizar tickets de soporte o realizar un cálculo complejo. Llámala en un bucle, incrementando el parámetro start, hasta que hayas procesado todas las totalEntries.

Uso con Agentes de IA

Configura tu agente de IA (p. ej., Cursor AI, Copilot) para conectarse a este servidor MCP.
Usa read_excel o read_json para una vista previa rápida y metadatos.
Usa get_chunk o get_json_chunk para iterar a través de archivos grandes en lotes para un análisis escalable.
Los archivos JSON con más de 1000 entradas usan automáticamente paginación para un rendimiento óptimo.

Ejemplo de Uso

Aquí tienes un ejemplo de cómo puedes usar este servidor MCP con un agente de IA para analizar archivos.

Importante: El servidor MCP requiere rutas de archivo absolutas por razones de seguridad y fiabilidad.

Analizando un Archivo Excel/CSV

Escenario: Quieres obtener un resumen de dummy_excel_file.xlsx.

1. Solicitud Inicial al Agente de IA:

Tú: ¿Puedes analizar el archivo en /home/john/documents/dummy_excel_file.xlsx y darme los nombres de las columnas y las primeras filas?

2. El Agente de IA usa la herramienta read_excel:

El agente haría una llamada a la herramienta similar a esta:

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

3. Respuesta del Servidor MCP:

Si el archivo es grande, el servidor devolverá una vista previa:

{
  "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."
}

Buscando en un Archivo JSON Grande

Escenario: Quieres encontrar todas las acciones con "TITAN" en su símbolo de negociación de un archivo JSON muy grande.

1. Solicitud Inicial al Agente de IA:

Tú: ¿Puedes encontrar todas las entradas en /data/NSE.json donde el trading_symbol contiene TITAN?

2. El Agente de IA usa la herramienta query_json:

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

3. Respuesta del Servidor MCP:

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

Analizando un Archivo JSON de Forma Iterativa

Escenario: Quieres analizar un gran conjunto de datos JSON de registros de empleados, fragmento por fragmento.

1. Solicitud Inicial al Agente de IA:

Tú: ¿Puedes analizar los datos de empleados en /home/john/data/employees.json y mostrarme el primer fragmento?

2. El Agente de IA usa la herramienta get_json_chunk:

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

3. Respuesta para Archivo JSON Grande:

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

🚀 Despliegue en la Nube

¡Despliega tu servidor MCP a internet para que otros puedan usarlo mediante transporte HTTP!

Despliegue Rápido en Railway

Haz fork/clon de este repositorio
Conéctate a Railway: railway.app → Nuevo Proyecto → Desplegar desde GitHub
Accede a tu servidor: https://your-app.railway.app/mcp

Usa Tu Servidor Desplegado

{
  "mcpServers": {
    "Excel Analyser MCP (Cloud)": {
      "type": "http", 
      "url": "https://your-app.railway.app/mcp"
    }
  }
}

📖 Guía de despliegue completa: Consulta docs/DEPLOYMENT.md para instrucciones detalladas, consideraciones de seguridad y plataformas alternativas.

📚 Documentación

Documentación adicional está disponible en el directorio docs/:

docs/DEPLOYMENT.md - Guía de despliegue completa para Railway y otras plataformas en la nube
docs/URL_SUPPORT.md - Guía para añadir soporte de URLs para manejar acceso a archivos basados en la nube

Notas

Tipos de archivo compatibles: archivos .xlsx, .csv y .json
Requisitos de archivos JSON: Deben contener un array de objetos
Archivos Excel: Solo se usa la primera hoja por defecto en operaciones por fragmentos
Paginación automática: Los archivos JSON con >1000 entradas usan automáticamente paginación
Tamaños de fragmento: 1000 por defecto para un rendimiento óptimo, configurable por solicitud
Manejo de errores: Mensajes de error completos para archivo no encontrado, formatos inválidos, etc.

Pruebas

El proyecto incluye archivos de prueba tanto para funcionalidad Excel/CSV como JSON en el directorio tests/:

tests/test-readExcelFile.js - Probar funcionalidad de lectura Excel/CSV
tests/test-readJsonFile.js - Probar funcionalidad de lectura JSON
tests/test-http-transport.js - Probar conectividad del transporte HTTP
tests/test-deployment.js - Probar funcionalidad del servidor desplegado
tests/test-data.json - Archivo JSON de muestra para pruebas
tests/dummy_excel_file.xlsx - Archivo Excel de muestra para pruebas Para ejecutar las pruebas:

# 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

Comentarios y Soporte

Valoramos tus comentarios y estamos comprometidos a mejorar Excel Analyser MCP. Aquí tienes varias formas de contactarnos:

🐛 ¿Encontraste un error?

GitHub Issues: Reporta errores aquí
Por favor incluye:
- Pasos para reproducir el problema
- Comportamiento esperado vs. real
- Tipo y tamaño de archivo (si aplica)
- Mensajes de error o registros

💡 Solicitudes de funciones y mejoras

GitHub Issues: Solicita funciones aquí
GitHub Discussions: Inicia una discusión para ideas y comentarios generales

📝 Comentarios generales

Email: contactakagrawal@gmail.com
GitHub Discussions: Comentarios generales

🤝 Contribuciones

¡Damos la bienvenida a las contribuciones! Consulta nuestras Guías de contribución para obtener más información sobre cómo:

Enviar solicitudes de extracción (pull requests)
Reportar problemas
Sugerir mejoras
Ayudar con la documentación

⭐ Muestra tu apoyo

Si encuentras útil este proyecto, considera:

Darle una ⭐ estrella en GitHub
Compartirlo con otras personas que puedan beneficiarse
Contribuir al código base

Licencia

ISC

Excel Analyser MCP

Documentación

Excel Analyser MCP

🚀 Inicio Rápido - Configuración

⚡ Servidor HTTP Listo para Usar (Recomendado)

Transporte NPM/Stdio (Autoalojado)

Transporte HTTP (Autoalojado)

Transporte SSE (Autoalojado)

Scripts de Desarrollo (Autoalojado)

Novedades en v2.1.0

Novedades en v2.0.0

Características

Primeros Pasos

Requisitos Previos

Instalación

Ejecutar el Servidor MCP

Herramientas MCP

1. read_excel

2. get_chunk

3. read_json

4. query_json

5. get_json_chunk

Cómo Elegir la Herramienta JSON Correcta

Uso con Agentes de IA

Ejemplo de Uso

Analizando un Archivo Excel/CSV

Buscando en un Archivo JSON Grande

Analizando un Archivo JSON de Forma Iterativa

🚀 Despliegue en la Nube

Despliegue Rápido en Railway

Usa Tu Servidor Desplegado

📚 Documentación

Notas

Pruebas

Comentarios y Soporte

🐛 ¿Encontraste un error?

💡 Solicitudes de funciones y mejoras

📝 Comentarios generales

🤝 Contribuciones

⭐ Muestra tu apoyo

Licencia

1. `read_excel`

2. `get_chunk`

3. `read_json`

4. `query_json`

5. `get_json_chunk`