OpenPyXL MCP Server

Um servidor MCP que encapsula a biblioteca OpenPyXL, permitindo que clientes recuperem dados de arquivos Excel.

Documentação

openpyxl_mcp_server

O que é isto?

Um wrapper leve em torno da biblioteca Python OpenPyXl que expõe alguns de seus recursos como servidor Model Context Protocol (MCP). Isso permite que o Claude e outros clientes MCP busquem dados de arquivos Excel.

Links relacionados:

Instalação

Etapas Gerais

Baixe a versão mais recente do executável em https://github.com/jonemo/openpyxl-mcp-server/releases.. openpyxl_mcp_server é para MacOS, openpyxl_mcp_server.exe é para Windows.
Para usuários de MacOS, certifique-se de definir permissões de execução no arquivo baixado: chmod a+x /path/to/openpyxl_mcp_server (substitua /path/to/ pelo local real do seu download).
Configure seu Cliente MCP. Na maioria dos casos, será o Claude Desktop; veja as instruções na próxima seção.

O Windows tentará te convencer a não executar um executável aleatório baixado da internet. Você terá que clicar em "Manter" ou "Manter mesmo assim" em vários lugares para convencê-lo a não excluir o arquivo. Os detalhes disso dependem do navegador que você usa e das configurações do Windows Defender.

Alternativamente, se você não confia nos meus executáveis, também pode instalar a versão do código-fonte diretamente deste repositório. Veja a seção "A partir do código-fonte" abaixo.

Configurando o Claude Desktop

Observe que isso só funciona com o aplicativo Claude Desktop, não com o Claude rodando no navegador web.

Tenha o Claude Desktop instalado.
Tenha o executável do servidor MCP baixado (veja a seção anterior). Isso pressupõe que você baixou o executável para sua pasta Downloads. Você pode usar qualquer outra pasta; ajuste os caminhos na configuração abaixo de acordo.
No Claude Desktop, abra o menu "Configurações...":
Navegue até a seção "Desenvolvedor" das configurações.
Clique em "Editar Config". Isso criará um arquivo de configuração para servidores MCP, caso você ainda não tenha um. O local padrão deste arquivo é:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
No MacOS, adicione o seguinte ao seu claude_desktop_config.json. Substitua <YOUR-USERNAME> pelo seu nome de usuário do MacOS. Se você já usa outros servidores MCP, terá que mesclar o JSON ao conteúdo existente.
```
{
  "mcpServers": {
    "inspect_excel_xlsx_file": {
      "command": "/Users/<YOUR-USERNAME>/Downloads/openpyxl_mcp_server",
      "args": []
    }
  }
}
```
No Windows, adicione o seguinte ao seu claude_desktop_config.json. Substitua <YOUR-USERNAME> pelo seu nome de usuário do MacOS. Se você já usa outros servidores MCP, terá que mesclar o JSON ao conteúdo existente.
```
{
  "mcpServers": {
    "inspect_excel_xlsx_file": {
      "command": "C:\\Users\\<YOUR-USERNAME>\\Downloads\\openpyxl_mcp_server.exe",
      "args": []
    }
  }
}
```
Após atualizar seu arquivo de configuração, você precisa reiniciar o aplicativo Claude para que as alterações tenham efeito. Não basta fechar a janela do aplicativo Claude. No Windows, você deve clicar com o botão direito no ícone do Claude na bandeja do sistema e selecionar "Sair". No macOS, você pode usar Command+Q.

Se você encontrar problemas, consulte estes recursos:

Documentação do Anthropic para usuários.
A seção "Testando seu servidor com Claude for Desktop" da documentação do Anthropic para desenvolvedores
Alguém também criou um gerador de arquivos de configuração em https://claudedesktopconfiggenerator.com/

Configurando outros clientes MCP

Instruções para configurar servidores MCP em outras ferramentas que os suportam:

A partir do código-fonte (para desenvolvimento)

Esta seção só se aplica se você deseja modificar o código-fonte ou se não confia nos executáveis fornecidos e prefere executar a partir do código-fonte.

git clone git@github.com:jonemo/openpyxl-mcp-server.git
cd openpyxl-mcp-server
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Supondo que você clonou seu repositório para /Users/jonas/repos/openpyxl_mcp_server, o conteúdo do arquivo de configuração agora deve mudar para:

{
  "mcpServers": {
    "inspect_excel_xlsx_file": {
      "command": "/Users/jonas/repos/openpyxl_mcp_server/venv/bin/python",
      "args": ["/Users/jonas/repos/openpyxl_mcp_server/openpyxl_mcp_server.py"]
    }
  }
}

Exemplos de prompts

Exemplo 1

Usa o arquivo KimbroughEvelyn_A-5qg0_Dataset_20160624.xlsx do conjunto de dados "Near-Port Air Quality Assessment Utilizing a Mobile Monitoring Approach" de https://catalog.data.gov/dataset/near-port-air-quality-assessment-utilizing-a-mobile-monitoring-approach

Em uma olhada rápida na descrição e no conteúdo do arquivo, não ficou óbvio para mim sobre quais portos esse conjunto de dados trata. Vamos perguntar ao Claude:

Tenho um arquivo Excel em ~/Downloads/KimbroughEvelyn_A-5qg0_Dataset_20160624.xlsx que contém dados associados a algum estudo sobre poluição do ar perto de um ou mais portos nos Estados Unidos. Você consegue inferir, a partir do conteúdo do arquivo, quais portos são cobertos por este estudo?

https://claude.ai/share/d87f67a9-dbc0-4223-86ff-3b4c1f9fa2e7

Após 11 chamadas ao servidor MCP, a resposta é:

Observando as coordenadas de latitude e longitude da planilha Fig 2 e combinando isso com as informações de localização, posso inferir que este estudo é focado no Porto de Charleston, Carolina do Sul.

As coordenadas no conjunto de dados (aproximadamente latitude 32.83 e longitude -79.87) correspondem à área de Charleston, e as referências a estações de monitoramento no centro da cidade, pátio ferroviário e aeroporto são consistentes com o monitoramento da qualidade do ar em torno de uma cidade portuária.

Este conjunto de dados parece conter medições de poluição do ar (PM2.5 e PM10) coletadas perto do Porto de Charleston, com comparações entre locais do porto e locais de referência/fundo.

Exemplo 2:

Sou o tesoureiro de uma pequena associação de proprietários de 10 unidades. Nossa contabilidade é feita em um arquivo Excel no Google Sheets. O arquivo tem 9 planilhas, com nove planilhas para coisas como a lista de transações, contas de mensalidades dos membros, relatórios trimestrais.

O arquivo contém informações não públicas, portanto este exemplo mostra apenas o prompt, alguns "insights" principais e a resposta final:

~/Downloads/CASH FLOW 2024.xlsx são as finanças da minha associação de proprietários. Quanto fomos cobrados pela manutenção do sistema de sprinklers em 2024? Quantas transações contribuíram para esse total? Quando cada transação ocorreu?

[...]

Vejo uma planilha "Transactions" que provavelmente contém os registros detalhados de despesas. Deixe-me procurar por "sprinkler" nesta planilha para encontrar transações relevantes:

[...]

Deixe-me examinar a planilha de resumo YEAR 2024 para ver se a manutenção de sprinklers está listada como uma categoria:

[...]

Ótimo! Encontrei "Sprinkler Maintenance" listado como uma categoria na linha 24 da planilha YEAR 2024. Agora, deixe-me verificar as transações reais relacionadas à manutenção de sprinklers:

[...]

Deixe-me verificar mais entradas pesquisando especificamente por "Sprinkler Maintenance" em toda a planilha Transactions:

[...]

Com base na minha análise dos registros financeiros da sua associação no arquivo "CASH FLOW 2024.xlsx", aqui está o que encontrei sobre as despesas de manutenção do sistema de sprinklers em 2024:

Valor total cobrado pela manutenção do sistema de sprinklers em 2024: $565,00 Número de transações: 1 transação Data da transação: 9 de setembro de 2024

A despesa aparece como uma única transação na planilha Transactions. A planilha também contém um valor orçado para manutenção de sprinklers de $750,00 para o ano na planilha "YEAR 2024 Actuals vs Planned", com uma nota afirmando "Nenhuma fatura recebida ainda" (o que pode estar desatualizado, pois agora há uma fatura registrada). Gostaria que eu analisasse outros aspectos das despesas de manutenção de sprinklers da sua associação ou outras informações financeiras da planilha?

História real. Nosso técnico de sprinklers só nos cobrou pela única visita na primavera e esqueceu de enviar a conta pelo trabalho feito mais tarde no ano. Não se preocupe, ele foi pago, mas está registrado em 2025.

Exemplo 3: Preenchendo um formulário

Minhas pesquisas no Google por planilhas Excel interessantes encontraram o formulário DPR 973 da California Natural Resources Agency: https://www.parks.ca.gov/pages/22374/files/Annual%20Report%20DPR973.xls Este parece ser um formulário que é preenchido por "associações" que apoiam os Parques Estaduais da Califórnia. Para ser claro, não sou afiliado a tal associação. Mas converti o formulário do formato .xls para .xlsx e pedi ao Claude para me ajudar a preenchê-lo:

Preciso arquivar o DPR973 porque trabalho para uma "associação cooperante" dos Parques Estaduais da Califórnia. O formulário que tenho que preencher é esta planilha Excel: /Users/jonas/Downloads/Annual Report DPR973.xlsx. Apoiamos os Parques Estaduais publicando livros e geramos receita vendendo lenha. Onde no livro de trabalho eu preciso preencher células?

Após 11 chamadas à ferramenta, a resposta parece correta, embora eu não entenda por que o Claude não olhou para as planilhas restantes:

Com base no meu exame do formulário DPR973, agora fornecerei orientações sobre onde você precisa preencher células para sua associação cooperante que publica livros e vende lenha:

Página 1:

Você precisará preencher as Informações da Associação (Parte I) com os detalhes da sua organização (nome, endereço, informações de contato)

Atualize o ano na célula C4 para o ano de relatório atual

Página 2 (A) - É aqui que você registrará suas informações de vendas:

Para suas vendas de livros (que seriam consideradas interpretativas/educacionais):

Linha 1 (Célula F22): Vendas Brutas - Materiais (para seus livros publicados)

Linha 2 (Célula F23): Quaisquer devoluções ou reembolsos

Linha 3 (Célula F24): Custo dos Produtos Vendidos para os livros

Para suas vendas de lenha:

Linha 23 (Célula F51): Vendas Brutas - Lenha

Linha 24 (Célula F52): Quaisquer reembolsos/lenha devolvida/danificada

Linha 25 (Célula F53): Custo dos Produtos Vendidos para lenha

O formulário calculará automaticamente os totais nas células F25 (lucros de livros), F54 (lucros de lenha) e F58 (lucros líquidos totais)

Página 3 - Resumo Financeiro:

Seus números de vendas serão preenchidos automaticamente da Página 2(A) em:

Linha 6 (Célula F11): Total de vendas brutas

Linha 7 (Célula F12): Total de custo de produtos/serviços + devoluções/reembolsos

Linha 8 (Célula H13): Lucros líquidos para todos os materiais e serviços

Você precisará inserir manualmente:

Quaisquer doações/contribuições (Linha 1, Célula F6)

Mensalidades de membros, se aplicável (Linha 4, Célula H9)

Renda de juros/investimentos, se houver (Linha 5, Célula H10)

Informações de captação de recursos, se aplicável (Linhas 9-11)

Outras receitas, se aplicável (Linha 12, Célula H17)

Para despesas:

Linha 15 (Célula F21): Quaisquer doações diretas aos Parques Estaduais da Califórnia

Linha 16 (Célula F22): Despesas de apoio a programas interpretativos

Linha 17 (Célula F23): Outro apoio a programas CSP

Linha 19 (Célula H25): Despesas administrativas e gerais

Para ativos/passivos:

Linha 22 (Célula F30): Total de ativos

Linha 23 (Célula H31): Total de passivos

Linhas 24-26 (Células F32-F34): Ativos líquidos por tipo de restrição

Página 4 (não examinada completamente, mas provavelmente contém):

Notas adicionais, explicações e assinaturas

Para suas atividades específicas (publicação de livros e venda de lenha), concentre-se em preencher com precisão:

A seção de Vendas Interpretativas e Educacionais na Página 2(A) para suas vendas de livros

A seção de Vendas de Lenha na Página 2(A) para sua receita de lenha

O resumo financeiro completo na Página 3

Gostaria que eu explicasse alguma seção específica com mais detalhes?

Exemplo 4

Este usa o arquivo 2025-3-7-iolp-buildings.xlsx do conjunto de dados Inventory of Owned and Leased Properties (IOLP) disponível em https://catalog.data.gov/dataset/inventory-of-owned-and-leased-properties-iolp Se você acompanhou as notícias nas últimas semanas, saberá por que este é atualmente o conjunto de dados mais popular no data.gov.

Prompt:

Usando o arquivo Excel em "/Users/jonas/Downloads/2025-3-7-iolp-buildings.xlsx": Qual é o maior edifício federal por metragem quadrada no estado de Utah?

Usei este arquivo e prompt repetidamente como caso de teste e obtive resultados mistos:

Conversas que terminaram sem resposta porque atingiram o limite de contexto. Isso aconteceu quando o Claude entrou em um loop consultando muitas linhas uma de cada vez.
Respostas incorretas porque o Claude fez "suposições ruins" ao longo do caminho. Por exemplo, em esta conversa, ele decide que o maior edifício deve estar em Salt Lake City e começa a pesquisar na planilha termos arbitrários.
Respostas corretas, por exemplo esta conversa: O IRS Service Center em Ogden é o maior edifício de propriedade federal em Utah na lista. Nota de rodapé: O IRS Service Center está correto na medida em que é o maior edifício da lista. O "Bumblehive", também conhecido como "Utah Data Center" ou "Intelligence Community Comprehensive National Cybersecurity Initiative Data Center", é quase certamente maior, mas não está incluído no arquivo.

Contribuição e Desenvolvimento

Criando executáveis independentes

Para criar executáveis independentes que não exigem instalação do Python:

Certifique-se de ter todas as dependências instaladas:

pip install -r requirements.txt
pip install -r requirements-dev.txt

Compile o executável:
```
pyinstaller openpyxl_mcp_server.spec
```

O executável será criado no diretório dist. No Windows, ele será nomeado openpyxl_mcp_server.exe. No macOS, ele será nomeado openpyxl_mcp_server.

Nota: Ao compilar no macOS, talvez seja necessário assinar o executável para que ele funcione corretamente. Você pode fazer isso com:

codesign --force --deep --sign - dist/openpyxl_mcp_server

Diretórios de Servidores MCP

openpyxl-mcp-server está atualmente listado nestes diretórios de servidores MCP: