Google Spreadsheet MCP

Integração completa com o Google Sheets - ler, escrever, formatar células, criar gráficos, usar fórmulas e gerenciar planilhas.

GitHub

Experimente este MCPPatrocinado

Documentação

Google Sheets MCP Server

Um servidor Model Context Protocol (MCP) que oferece funcionalidade completa do Google Sheets. Leia, escreva, formate células, crie gráficos, use fórmulas e gerencie planilhas diretamente do Claude, Cursor ou qualquer cliente compatível com MCP.

Por que eu construí isso

Criei este servidor MCP para meus trabalhos da faculdade, onde trabalho frequentemente com dados no Google Sheets — principalmente planilhas financeiras. Tarefas como criar gráficos, escrever fórmulas, formatar tabelas e organizar dados eram repetitivas e demoradas. Com esta ferramenta, posso automatizar tudo isso e focar no que realmente importa — raciocínio lógico e análise — em vez de fazer o mesmo trabalho manual repetidamente. :)

Recursos

Categoria	Recursos
Operações de Célula	Ler, escrever, operações em lote, anexar linhas, limpar células
Fórmulas	Suporte completo (`=SUM()`, `=VLOOKUP()`, `=IF()`, etc.)
Gerenciamento de Abas	Criar, excluir, renomear, duplicar abas
Formatação	Negrito, itálico, cores, alinhamento, larguras de coluna, mesclar células
Gráficos	Gráficos de barras, linhas, pizza, colunas, área, dispersão
Operações de Dados	Ordenar, localizar/substituir, obter última linha
Compartilhamento	Compartilhar com usuários ou tornar público

Início Rápido

1. Instalação

cd /path/to/spreadsheet-mcp
uv sync

2. Configuração do Google Cloud (Grátis, Única Vez)

Criar Projeto: Acesse o Google Cloud Console → Novo Projeto
Habilitar APIs:
- Habilitar API do Sheets
- Habilitar API do Drive
Criar Conta de Serviço:
- Acesse APIs & Services → Credenciais → Criar Credenciais → Conta de Serviço
- Baixe a chave JSON → Salve como credentials/service-account.json
Compartilhar Planilhas: Compartilhe suas planilhas com o e-mail da conta de serviço (encontrado no JSON)

3. Executar

uv run spreadsheet-mcp

Configuração do Cliente MCP

Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Claude Code (CLI)

Adicione ao arquivo .mcp.json do seu projeto:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Cursor

Adicione às configurações de MCP do Cursor (Configurações → MCP → Adicionar Servidor):

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Ou adicione ao ~/.cursor/mcp.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Gemini CLI

Para o Gemini CLI com suporte a MCP, adicione à sua configuração MCP:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Usando com npx (Alternativa)

Se você preferir npx em vez de uv:

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": [
        "-y",
        "uv",
        "--directory",
        "/path/to/spreadsheet-mcp",
        "run",
        "spreadsheet-mcp"
      ]
    }
  }
}

Nota: Substitua /path/to/spreadsheet-mcp pelo caminho real onde você clonou este repositório.

Ferramentas Disponíveis (27 no Total)

Gerenciamento de Planilhas e Abas

Ferramenta	Descrição	Exemplo
`get_spreadsheet_info`	Obter metadados e lista de abas	"Mostre-me informações sobre a planilha abc123"
`create_spreadsheet`	Criar nova planilha	"Crie uma planilha chamada 'Orçamento 2024'"
`list_sheets`	Listar todas as abas	"Quais abas existem nesta planilha?"
`create_sheet`	Adicionar uma nova aba	"Adicione uma aba chamada 'Resumo'"
`delete_sheet`	Remover uma aba	"Exclua a aba com ID 12345"
`rename_sheet`	Renomear uma aba	"Renomeie a aba 0 para 'Dados'"
`duplicate_sheet`	Copiar uma aba	"Duplique a aba principal"

Operações de Célula

Ferramenta	Descrição	Exemplo
`read_cells`	Ler valores de um intervalo	"Leia as células A1 a D10 da Sheet1"
`write_cells`	Escrever valores (suporta fórmulas)	"Escreva os cabeçalhos Nome, Idade, Pontuação em A1"
`batch_read`	Ler vários intervalos de uma vez	"Leia A1:A10 e C1:C10"
`batch_write`	Escrever em vários intervalos	"Escreva dados em vários locais"
`append_rows`	Adicionar linhas no final dos dados	"Anexe estes novos registros"
`clear_cells`	Limpar um intervalo	"Limpe as células B2:D10"
`get_last_row`	Encontrar a última linha com dados	"Qual é a última linha na coluna A?"

Operações de Linha/Coluna

Ferramenta	Descrição	Exemplo
`insert_rows`	Inserir linhas vazias	"Insira 5 linhas na linha 10"
`insert_columns`	Inserir colunas vazias	"Insira 2 colunas na coluna C"
`delete_rows`	Excluir linhas	"Exclua as linhas 5-10"
`delete_columns`	Excluir colunas	"Exclua a coluna B"

Formatação

Ferramenta	Descrição	Exemplo
`format_cells`	Aplicar formatação	"Deixe a linha de cabeçalho em negrito com fundo azul"
`set_column_width`	Ajustar largura da coluna	"Defina a largura da coluna A para 200 pixels"
`merge_cells`	Mesclar intervalo de células	"Mescle as células A1:C1 para o título"

Gráficos

Ferramenta	Descrição	Exemplo
`create_chart`	Criar gráfico incorporado	"Crie um gráfico de barras a partir dos dados de vendas"
`list_charts`	Listar todos os gráficos	"Quais gráficos existem nesta planilha?"
`delete_chart`	Remover um gráfico	"Exclua o gráfico 123456"

Operações de Dados

Ferramenta	Descrição	Exemplo
`sort_range`	Ordenar dados por coluna	"Ordene os dados pela coluna B em ordem crescente"
`find_replace`	Localizar e substituir texto	"Substitua 'N/A' por '0' em todos os lugares"

Compartilhamento

Ferramenta	Descrição	Exemplo
`share_spreadsheet`	Compartilhar ou tornar público	"Torne esta planilha pública"

Exemplos de Uso

Exemplo 1: Criar um Relatório de Vendas

User: Create a sales report in spreadsheet abc123

Claude will:
1. get_spreadsheet_info("abc123") - Check existing sheets
2. create_sheet("abc123", "Sales Report") - Create new sheet
3. write_cells("abc123", "Sales Report!A1", '[["Product", "Q1", "Q2", "Q3", "Q4", "Total"]]')
4. write_cells("abc123", "Sales Report!A2", '[["Widget", 100, 150, 200, 180, "=SUM(B2:E2)"]]')
5. format_cells(..., bold=True, background_color="#4285F4") - Format header
6. create_chart(..., "COLUMN", "Quarterly Sales") - Add chart

Exemplo 2: Analisar Dados Existentes

User: Summarize the data in Sheet1

Claude will:
1. read_cells("abc123", "Sheet1!A1:Z1") - Read headers
2. get_last_row("abc123", "Sheet1", "A") - Find data extent
3. read_cells("abc123", "Sheet1!A1:D100") - Read all data
4. Provide summary and insights

Exemplo 3: Formatar uma Tabela

User: Make the spreadsheet look professional

Claude will:
1. format_cells(..., bold=True, background_color="#1a73e8", font_color="#FFFFFF") - Header
2. set_column_width(..., 150) - Adjust widths
3. format_cells(..., alignment="CENTER") - Center data

Referência de Notação A1

Notação	Descrição
`Sheet1!A1:D10`	Células A1 a D10 na Sheet1
`Sheet1!A:A`	Coluna A inteira na Sheet1
`Sheet1!1:5`	Linhas 1-5 na Sheet1
`A1:B10`	Intervalo na primeira aba visível
`'My Sheet'!A1`	Nome da aba com espaços (use aspas)

Referência de Índice

Linhas: base 0 na formatação (Linha 1 = índice 0)
Colunas: base 0 (A=0, B=1, C=2, D=3...)
sheet_id: ID numérico de list_sheets ou get_spreadsheet_info

Fórmulas Comuns

=SUM(A1:A10)           Sum values
=AVERAGE(B:B)          Average entire column
=COUNT(A:A)            Count numbers
=COUNTA(A:A)           Count non-empty cells
=MAX(A1:A100)          Maximum value
=MIN(A1:A100)          Minimum value
=VLOOKUP(A1,B:C,2,0)   Lookup value
=IF(A1>100,"High","Low") Conditional
=CONCATENATE(A1," ",B1)  Join text
=TODAY()               Current date
=NOW()                 Current date/time

Solução de Problemas

Erro	Solução
"Credenciais da conta de serviço não encontradas"	Verifique se `credentials/service-account.json` existe
"403 Proibido"	Compartilhe a planilha com o e-mail da conta de serviço
"API não habilitada"	Habilite as APIs do Sheets e do Drive no Google Cloud Console
"Cota excedida"	Espere um minuto, você está atingindo os limites de taxa

Estrutura de Arquivos

spreadsheet-mcp/
├── pyproject.toml
├── README.md
├── credentials/
│   └── service-account.json  (your key, gitignored)
└── src/spreadsheet_mcp/
    ├── __init__.py
    ├── auth.py              # Google authentication
    ├── sheets_client.py     # API wrapper (1000+ lines)
    └── server.py            # MCP server (27 tools)

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Autor

@dudegladiator

Licença

MIT