Excel Analyser MCP

Leia e analise arquivos Excel (.xlsx) e CSV (.csv) com acesso escalável, em partes e específico por coluna, ideal para grandes conjuntos de dados.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Excel Analyser MCP

MCP Badge npm version npm downloads License MCP Server

Um servidor MCP em Node.js para ler e analisar arquivos Excel (.xlsx), CSV (.csv) e JSON (.json). Suporta múltiplos protocolos de transporte (stdio, HTTP, SSE) e foi projetado para acesso escalável, em blocos e específico por coluna/campo, tornando-o ideal para agentes de IA e fluxos de automação que precisam processar grandes conjuntos de dados com eficiência.

🚀 Início Rápido - Configuração

O Excel Analyser MCP suporta múltiplos protocolos de transporte: stdio (npm/CLI), HTTP streamable e SSE.

⚡ Servidor HTTP Pronto para Uso (Recomendado)

A maneira mais rápida de começar! Use nosso servidor implantado sem qualquer instalação:

Configuração do Cliente MCP (HTTP - Pronto para Uso):

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

🎉 É isso! Nenhuma instalação necessária. Comece a analisar arquivos imediatamente.

📝 Exemplo de Prompt de Uso (HTTP - Use URLs na Nuvem):

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: Use URLs na nuvem (GitHub raw, links públicos do Google Drive, etc.) pois o servidor roda remotamente e não pode acessar seus arquivos locais.

Transporte NPM/Stdio (Auto-hospedado)

Perfeito para clientes MCP como Claude Desktop, Cursor e outras integrações baseadas em CLI.

Configuração do mcp.json:

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

📝 Exemplo de Prompt de Uso (Stdio - Use Caminhos Locais):

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: Use caminhos de arquivo locais absolutos pois o servidor roda na sua máquina e pode acessar seus arquivos locais diretamente.

Transporte HTTP (Auto-hospedado)

Ideal para aplicações web, integrações com API REST e implantações 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

Configuração do Cliente MCP (HTTP):

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

📝 Exemplo de Prompt de Uso (HTTP Auto-hospedado - Use URLs Locais ou na Nuvem):

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 Auto-hospedado: Você pode usar caminhos absolutos locais ou URLs na nuvem pois seu servidor pode acessar tanto arquivos locais quanto URLs remotas.

Transporte SSE (Auto-hospedado)

Para aplicações de streaming em tempo real (obsoleto, mas ainda suportado).

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

Configuração do Cliente MCP (SSE):

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

Scripts de Desenvolvimento (Auto-hospedado)

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

Novidades na v2.1.0

  • 🚀 Suporte Multi-Transporte: Agora suporta transportes stdio (npm), HTTP streamable e SSE para máxima flexibilidade
  • 🔗 Transporte HTTP: Perfeito para aplicações web e integrações com API REST
  • 📡 Transporte SSE: Capacidades de streaming em tempo real para casos de uso avançados
  • ⚙️ Configuração Fácil: Argumentos simples de linha de comando para escolher seu transporte preferido

Novidades na v2.0.0

  • Nova Ferramenta query_json: Uma ferramenta poderosa e nova para pesquisar eficientemente grandes arquivos JSON com base em valores de campos.
  • Streaming Eficiente: Todas as ferramentas JSON (read_json, query_json, get_json_chunk) foram re-arquitetadas para usar streaming. Isso significa que podem processar arquivos de tamanho gigabyte com uso mínimo de memória, prevenindo travamentos e garantindo escalabilidade.

Recursos

  • Suporte Multi-Transporte: Escolha entre transportes stdio (npm), HTTP streamable ou SSE
  • Leia arquivos Excel/CSV/JSON e produza todas ou colunas/campos selecionados como JSON
  • Streaming Eficiente: Lide com arquivos JSON de vários gigabytes com uso de memória constante e baixo.
  • Consulta JSON Poderosa: Pesquise e filtre rapidamente grandes arquivos JSON sem carregar o arquivo inteiro na memória.
  • Acesso em Blocos: Processe grandes arquivos iterativamente buscando dados em blocos configuráveis.
  • Filtragem por Coluna/Campo: Extraia apenas as colunas ou campos que você precisa.
  • Integração com servidor MCP: Exponha ferramentas para agentes de IA e automação.

Começando

Pré-requisitos

  • Node.js (v18 ou superior recomendado)

Instalação

npm install
yarn install # or your preferred package manager

Executando o Servidor MCP

node excel-analyser-mcp.js

Ou configure seu agente MCP para iniciar este arquivo com Node.js e --stdio.

Ferramentas MCP

1. read_excel

Descrição: Lê um arquivo Excel ou CSV e retorna uma prévia (primeiras 100 linhas) e metadados para arquivos grandes, ou os dados completos para arquivos pequenos.

Parâmetros:

  • filePath (string, obrigatório): Caminho para o arquivo Excel ou CSV no disco (.xlsx ou .csv)
  • columns (array de strings, opcional): Colunas a incluir na saída. Se não especificado, todas as colunas são incluídas.

Retorna:

  • Para arquivos grandes: { preview: [...], totalRows, columns, message }
  • Para arquivos pequenos: Dados completos como um array

Exemplo de Solicitação:

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

2. get_chunk

Descrição: Busca um bloco de linhas de um arquivo CSV ou Excel, com filtragem opcional de colunas. Útil para processar arquivos grandes em lotes.

Parâmetros:

  • filePath (string, obrigatório): Caminho para o arquivo Excel ou CSV no disco (.xlsx ou .csv)
  • columns (array de strings, opcional): Colunas a incluir na saída
  • start (inteiro, opcional, padrão 0): Índice da linha para começar (baseado em 0)
  • limit (inteiro, opcional, padrão 1000): Número de linhas a retornar no bloco

Retorna:

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

Exemplo de Solicitação:

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

Exemplo de Resposta:

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

3. read_json

Descrição: Lê eficientemente um arquivo JSON grande para fornecer uma prévia rápida (primeiras 100 entradas) e metadados sem carregar o arquivo inteiro na memória. Este é o primeiro passo recomendado para analisar um novo arquivo JSON.

Parâmetros:

  • filePath (string, obrigatório): Caminho para o arquivo JSON no disco (.json)
  • fields (array de strings, opcional): Campos a incluir na saída. Se não especificado, todos os campos são incluídos.

Retorna:

  • Para arquivos grandes (>1000 entradas): { preview: [...], totalEntries, fields, message }
  • Para arquivos pequenos: Dados completos como um array

Exemplo de Solicitação:

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

Exemplo de Resposta (arquivo 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

Descrição: Realiza uma pesquisa rápida e eficiente em memória em um arquivo JSON grande. Ele transmite o arquivo e retorna todas as entradas que correspondem à consulta especificada, até um limite de 1000 resultados. Esta é a ferramenta ideal para encontrar dados específicos em um grande conjunto de dados.

Parâmetros:

  • filePath (string, obrigatório): Caminho para o arquivo JSON no disco (.json).
  • query (objeto, obrigatório): A consulta a executar nos dados JSON.
    • field (string): O campo a consultar (ex.: 'trading_symbol').
    • operator (enum): O operador da consulta. Pode ser contains, equals, startsWith ou endsWith.
    • value (string): O valor a comparar.

Retorna:

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

Exemplo de Solicitação:

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

Exemplo de Resposta:

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

Descrição: Busca um bloco específico de entradas de um arquivo JSON. Esta ferramenta é projetada para análise iterativa, onde você precisa processar cada entrada do arquivo sequencialmente, um bloco por vez. Ela usa streaming eficiente para acessar o bloco solicitado sem reler o arquivo inteiro.

Parâmetros:

  • filePath (string, obrigatório): Caminho para o arquivo JSON no disco (.json)
  • fields (array de strings, opcional): Campos a incluir na saída
  • start (inteiro, opcional, padrão 0): Índice da entrada para começar (baseado em 0)
  • limit (inteiro, opcional, padrão 1000): Número de entradas a retornar no bloco

Retorna:

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

Exemplo de Solicitação:

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

Exemplo de Resposta:

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

Como Escolher a Ferramenta JSON Correta

Use este guia para selecionar a ferramenta mais eficiente para sua tarefa:

  • Para explorar um novo arquivo JSON:

    • 1º: Use read_json. Ele fornecerá o número total de entradas, todos os campos disponíveis e uma prévia das primeiras 100 entradas.

  • Para encontrar dados específicos:

    • Use query_json. É a maneira mais rápida e eficiente em memória de pesquisar entradas que correspondem a uma condição específica (ex.: encontrar todos os usuários onde status é active).

  • Para processar cada entrada:

    • Use get_json_chunk. Isso é para quando você precisa executar uma ação em cada entrada do arquivo, como categorizar tickets de suporte ou realizar um cálculo complexo. Chame-o em um loop, incrementando o parâmetro start, até processar todas as totalEntries.

Uso com Agentes de IA

  • Configure seu agente de IA (ex.: Cursor AI, Copilot) para conectar-se a este servidor MCP.
  • Use read_excel ou read_json para uma prévia rápida e metadados.
  • Use get_chunk ou get_json_chunk para iterar por arquivos grandes em lotes para análise escalável.
  • Arquivos JSON com mais de 1000 entradas usam automaticamente paginação para desempenho ideal.

Exemplo de Uso

Aqui está um exemplo de como você pode usar este servidor MCP com um agente de IA para analisar arquivos.

Importante: O servidor MCP requer caminhos de arquivo absolutos por razões de segurança e confiabilidade.

Analisando um Arquivo Excel/CSV

Cenário: Você quer obter um resumo de dummy_excel_file.xlsx.

1. Solicitação Inicial ao Agente de IA:

Você: Pode analisar o arquivo em /home/john/documents/dummy_excel_file.xlsx e me dar os nomes das colunas e as primeiras linhas?

2. O Agente de IA usa a ferramenta read_excel:

O agente faria uma chamada de ferramenta semelhante a esta:

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

3. Resposta do Servidor MCP:

Se o arquivo for grande, o servidor retornará uma prévia:

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

Pesquisando um Arquivo JSON Grande

Cenário: Você quer encontrar todas as ações com "TITAN" em seu símbolo de negociação em um arquivo JSON muito grande.

1. Solicitação Inicial ao Agente de IA:

Você: Pode encontrar todas as entradas em /data/NSE.json onde o trading_symbol contém TITAN?

2. O Agente de IA usa a ferramenta query_json:

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

3. Resposta do Servidor MCP:

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

Analisando um Arquivo JSON Iterativamente

Cenário: Você quer analisar um grande conjunto de dados JSON de registros de funcionários, bloco por bloco.

1. Solicitação Inicial ao Agente de IA:

Você: Pode analisar os dados de funcionários em /home/john/data/employees.json e me mostrar o primeiro bloco?

2. O Agente de IA usa a ferramenta get_json_chunk:

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

3. Resposta para Arquivo JSON Grande:

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

🚀 Implantação na Nuvem

Implante seu servidor MCP na internet para que outros possam usá-lo via transporte HTTP!

Implantação Rápida no Railway

  1. Faça fork/clone deste repositório
  2. Conecte ao Railway: railway.app → Novo Projeto → Implantar do GitHub
  3. Acesse seu servidor: https://your-app.railway.app/mcp

Use Seu Servidor Implantado

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

📖 Guia completo de implantação: Veja docs/DEPLOYMENT.md para instruções detalhadas, considerações de segurança e plataformas alternativas.

📚 Documentação

Documentação adicional está disponível no diretório docs/:

  • docs/DEPLOYMENT.md - Guia completo de implantação para Railway e outras plataformas de nuvem
  • docs/URL_SUPPORT.md - Guia para adicionar suporte a URL para lidar com acesso a arquivos baseados em nuvem

Notas

  • Tipos de arquivo suportados: Arquivos .xlsx, .csv e .json
  • Requisitos de arquivos JSON: Devem conter um array de objetos
  • Arquivos Excel: Apenas a primeira planilha é usada por padrão em operações em blocos
  • Paginação automática: Arquivos JSON com >1000 entradas usam automaticamente paginação
  • Tamanhos de bloco: Padrão de 1000 para desempenho ideal, configurável por solicitação
  • Tratamento de erros: Mensagens de erro abrangentes para arquivo não encontrado, formatos inválidos, etc.

Testes

O projeto inclui arquivos de teste para funcionalidade Excel/CSV e JSON no diretório tests/:

  • tests/test-readExcelFile.js - Testar funcionalidade de leitura Excel/CSV
  • tests/test-readJsonFile.js - Testar funcionalidade de leitura JSON
  • tests/test-http-transport.js - Testar conectividade do transporte HTTP
  • tests/test-deployment.js - Testar funcionalidade do servidor implantado
  • tests/test-data.json - Arquivo JSON de amostra para testes
  • tests/dummy_excel_file.xlsx - Arquivo Excel de amostra para testes Para executar os testes:
# 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 e Suporte

Valorizamos seu feedback e estamos comprometidos em melhorar o Excel Analyser MCP. Aqui estão várias formas de entrar em contato:

🐛 Encontrou um Bug?

  • GitHub Issues: Relate bugs aqui
  • Por favor, inclua:
    • Passos para reproduzir o problema
    • Comportamento esperado versus comportamento real
    • Tipo e tamanho do arquivo (se aplicável)
    • Mensagens de erro ou logs

💡 Solicitações de Recursos e Melhorias

📝 Feedback Geral

🤝 Contribuindo

Aceitamos contribuições! Consulte nossas Diretrizes de Contribuição para mais informações sobre como:

  • Enviar pull requests
  • Relatar problemas
  • Sugerir melhorias
  • Ajudar com a documentação

⭐ Mostre Seu Apoio

Se você achar este projeto útil, considere:

  • Dar uma ⭐ estrela no GitHub
  • Compartilhar com outras pessoas que possam se beneficiar
  • Contribuir com o código

Licença

ISC