Excel Copilot MCP

Servidor Model Context Protocol (MCP) para o Cursor (e outros clientes compatíveis) que permite ao assistente ler e alterar o Microsoft Excel já aberto no seu computador, em linguagem natural.

• Plataforma: apenas Windows (automação COM).
• Distribuição: um arquivo excel-mcp.exe — não é necessário instalar Python.
• Excel: deve estar aberto com uma pasta de trabalho; o assistente usa o arquivo ativo e a aba ativa (salvo quando a ferramenta indica outra aba).

O que isso faz

1. Você configura o MCP no Cursor apontando para o excel-mcp.exe.
2. Abre o Excel com a sua planilha.
3. No Agent do Cursor, pede por exemplo: “Lê a aba ativa e resume”, “Deixa a linha 1 azul com texto branco”, “Cria um gráfico com A1:B15”.

O executável se conecta ao Excel em execução (não abre uma nova instância). As respostas vêm em JSON (status, result, message; às vezes cells_modified). Muitas operações focam a célula ou o intervalo no Excel e mostram uma mensagem na barra de status. Muitas operações também ajustam a área visível para o que foi alterado.

Requisitos

| Requisito | Detalhe | |-----------|---------| | Sistema | Windows 10 ou superior | | Excel | Microsoft Excel para Windows (COM disponível) | | Cursor | Versão com suporte a MCP | | Arquivos | excel-mcp.exe + este README |

Não funciona no macOS (não usa Office.js; usa automação COM, específica do Excel no Windows).

Instalação no Cursor

1. Colocar o executável

Salve o excel-mcp.exe em uma pasta fixa, por exemplo:

C:\tools\excel-mcp\excel-mcp.exe

Evite pastas que o Windows apague ou sincronize de forma imprevisível sem testar antes.

2. Configurar o MCP

Abra o arquivo de configuração MCP do Cursor. O caminho pode variar; exemplos comuns:

• %USERPROFILE%\.cursor\mcp.json
• %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json

Adicione (ou mescle com o que já existe) uma entrada como esta — ajuste o caminho do command para onde você colocou o .exe:

{
  "mcpServers": {
    "excel-copilot": {
      "command": "C:\\tools\\excel-mcp\\excel-mcp.exe",
      "args": []
    }
  }
}

No JSON no Windows, use \\ nas barras do caminho, como no exemplo.

3. Reiniciar o Cursor

Feche e abra o Cursor de novo para carregar o servidor.

4. Antes de cada sessão

• Abra o Excel e a pasta de trabalho com a qual você quer trabalhar.
• O assistente usa o workbook ativo; se houver vários arquivos no mesmo Excel, deixe em primeiro plano a janela do arquivo certo antes de pedir ações.

Utilização

1. Excel aberto com dados.
2. No Cursor, abra o Agent (chat com ferramentas).
3. Fale em português ou inglês, por exemplo:

• “Resume o que está na aba ativa.”
• “Explica a fórmula em D4.”
• “Formata A1:F1 com fundo azul escuro e letra branca em negrito.”
• “Procura erros na planilha e diz onde estão.”
• “Cria um gráfico de colunas com os dados de A1:C20.”

Se algo falhar, confira se o Excel continua aberto e se o arquivo certo está em primeiro plano.

Lista de ferramentas

O servidor expõe ferramentas MCP que o modelo escolhe automaticamente. Abaixo, uma visão geral por grupo.

Leitura

| Ferramenta | Função | |------------|--------| | get_workbook_info | Nome do arquivo, caminho, lista de abas, aba ativa, área usada por aba. | | read_active_sheet | Valores e fórmulas da aba ativa (limite max_rows, padrão 200). | | read_range | Lê um intervalo (ex.: A1:D10 ou NomeDaAba!A1:D10). | | read_selected_range | Lê o que o usuário tem selecionado no Excel. | | get_all_sheets_summary | Resumo de todas as abas (amostra de linhas, contagem de erros). | | find_errors | Localiza células com erro (#N/A, #REF!, …) em uma aba ou em toda a pasta de trabalho. | | get_formula_dependencies | Precedentes e dependentes de uma célula. | | search_in_workbook | Busca texto na pasta de trabalho (exata ou parcial). |

Escrita

| Ferramenta | Função | |------------|--------| | set_cell_value | Escreve valor em uma célula. | | set_range_values | Escreve matriz 2D em um intervalo. | | apply_formula | Define a fórmula de uma célula. | | apply_formula_to_range | Aplica várias fórmulas para baixo ou para a direita. | | clear_range | Limpa valores e/ou formatos. | | sort_range | Ordena um intervalo por coluna. | | fill_down | Preenchimento para baixo a partir da primeira célula do intervalo. |

Formatação

| Ferramenta | Função | |------------|--------| | format_range | Negrito, cores, bordas, formato numérico, alinhamento, etc. | | auto_fit_columns / auto_fit_rows | Ajustar largura de colunas ou altura de linhas. | | merge_cells | Mesclar ou desfazer células mescladas. | | apply_conditional_format | Regras como maior que, entre, top N, barras, escala de cores. | | freeze_panes | Congelar linhas/colunas. |

Gráficos

| Ferramenta | Função | |------------|--------| | create_chart | Cria gráfico (barras, colunas, linhas, pizza, etc.). | | delete_chart | Remove um gráfico pelo nome. | | list_charts | Lista gráficos da aba ou da pasta de trabalho. |

Análise

| Ferramenta | Função | |------------|--------| | summarize_sheet | Resumo estruturado da aba ativa (métricas, amostra). | | explain_formula | Devolve a fórmula e notas para o modelo explicar. | | variance_analysis | Compara dois intervalos (ex.: real vs orçamento). | | what_if_analysis | Altera temporariamente uma célula, recalcula e lê as saídas. | | find_duplicates | Valores repetidos em um intervalo. | | calculate_statistics | Soma, média, mediana, mín., máx., desvio padrão, contagens. |

Abas e pasta de trabalho

| Ferramenta | Função | |------------|--------| | add_sheet / delete_sheet / rename_sheet | Criar, excluir (com confirmação explícita), renomear abas. | | copy_sheet / move_sheet | Duplicar ou reordenar abas. | | set_sheet_tab_color | Cor da guia da aba. | | navigate_to_cell | Ir até uma célula e exibi-la. | | save_workbook | Salvar (ou Salvar como com caminho). | | protect_sheet | Proteger ou desproteger aba (opcionalmente com senha). | | add_comment | Comentário em uma célula. |

UX no Excel

| Ferramenta | Função | |------------|--------| | set_excel_status_bar | Texto na barra de status; vazio restaura o padrão. | | focus_range_in_excel | Seleciona um intervalo e ajusta a área visível. |

Nota: delete_sheet deve ser chamada com confirm=True somente depois de o usuário confirmar no chat que pode excluir a aba.

Várias pastas de trabalho ou instâncias do Excel

• Vários arquivos na mesma janela do Excel: o MCP usa a pasta de trabalho ativa (a que está em primeiro plano).
• Várias janelas ou processos do Excel: o comportamento depende do Windows/COM; o mais seguro é usar uma janela do Excel e deixar ativo o arquivo desejado.

Problemas frequentes

| Problema | O que verificar | |----------|-----------------| | “Nenhuma instância do Excel” | Abra o Excel antes de usar as ferramentas. | | O assistente altera o arquivo errado | Deixe em primeiro plano a janela do arquivo certo no Excel. | | MCP não aparece | Caminho do .exe no JSON, vírgulas no JSON, reinício do Cursor. | | Antivírus bloqueia o .exe | Assinatura / pasta confiável / exceção (comum em binários empacotados). |

Privacidade e segurança

• O Cursor envia solicitações ao modelo conforme as regras da sua conta.
• O excel-mcp.exe roda localmente e se comunica com o Excel no seu computador via COM; não é um add-in Office.js na nuvem.
• Evite compartilhar dados sensíveis em prompts se a política da sua organização não permitir.

Créditos e licença

Model Context Protocol: modelcontextprotocol.io.

Ajuste a licença e os créditos ao publicar o repositório de distribuição.