Google Sheets

Um servidor para integração abrangente com o Google Sheets, exigindo credenciais OAuth do Google.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP do Google Sheets

Um servidor Model Context Protocol (MCP) que fornece integração abrangente com o Google Sheets. Este servidor permite criar, ler, atualizar e gerenciar planilhas do Google Sheets programaticamente.

🎯 Objetivo

Este servidor permite que você:

  • Crie novas planilhas do Google Sheets com nomes de planilha personalizados
  • Leia dados de qualquer intervalo em uma planilha
  • Escreva dados em intervalos específicos
  • Adicione novas linhas a dados existentes
  • Limpe intervalos de dados
  • Obtenha informações e metadados da planilha
  • Atualize em lote múltiplos intervalos de forma eficiente

🛠️ Ferramentas Disponíveis

Operações Principais

  • create-spreadsheet

    • Cria uma nova planilha do Google Sheets
    • Entrada: title (obrigatório), sheet_names (array opcional)
    • Retorna: ID da planilha, URL e nomes das planilhas criadas

  • read-range

    • Lê dados de um intervalo específico
    • Entrada: spreadsheet_id, range_name (ex.: 'Sheet1!A1:C10')
    • Retorna: array 2D de valores de células

  • write-range

    • Escreve dados em um intervalo específico (substitui dados existentes)
    • Entrada: spreadsheet_id, range_name, values (array 2D)
    • Retorna: estatísticas de atualização

  • append-rows

    • Adiciona linhas ao final de um intervalo
    • Entrada: spreadsheet_id, range_name, values (array 2D)
    • Retorna: estatísticas de atualização

  • clear-range

    • Limpa todos os dados de um intervalo especificado
    • Entrada: spreadsheet_id, range_name
    • Retorna: confirmação do intervalo limpo

  • get-spreadsheet-info

    • Obtém metadados sobre uma planilha
    • Entrada: spreadsheet_id
    • Retorna: título, URL, informações da planilha, dimensões

  • batch-update

    • Realiza múltiplas atualizações de intervalos em uma única solicitação
    • Entrada: spreadsheet_id, updates (array de pares de intervalo/valores)
    • Retorna: estatísticas totais de atualização

Prompts

  • manage-sheets: Prompt geral de gerenciamento do Google Sheets para assistentes de IA

🚀 Configuração

1. Configuração da API do Google Sheets

  1. Crie um projeto do Google Cloud ou use um existente
  2. Ative a API do Google Sheets
  3. Configure uma tela de consentimento OAuth
    • Selecione "Externo" para fins de teste
    • Adicione seu e-mail como usuário de teste
  4. Adicione o escopo OAuth: https://www.googleapis.com/auth/spreadsheets
  5. Crie credenciais de ID do Cliente OAuth 2.0
    • Escolha "Aplicativo de Desktop"
  6. Baixe o arquivo JSON de credenciais
  7. Salve-o com segurança e anote o caminho do arquivo

2. Instalação

Usando uv (recomendado):

cd sheets-mcp-server
uv sync

3. Autenticação

Na primeira execução, o servidor abrirá um navegador para autenticação OAuth. Os tokens de acesso serão salvos no --token-path especificado para uso futuro.

💼 Uso

Uso Independente

uv run sheets \
  --creds-file-path /path/to/your/credentials.json \
  --token-path /path/to/your/tokens.json

Integração com o Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/sheets-mcp-server",
        "run",
        "sheets",
        "--creds-file-path",
        "/path/to/your/credentials.json",
        "--token-path",
        "/path/to/your/tokens.json"
      ]
    }
  }
}

Integração com Outros Clientes MCP

Este servidor segue o protocolo MCP padrão e pode ser integrado com qualquer cliente compatível com MCP.

📋 Exemplos de Uso

Criando uma Nova Planilha

{
  "tool": "create-spreadsheet",
  "arguments": {
    "title": "My Data Analysis",
    "sheet_names": ["Data", "Analysis", "Charts"]
  }
}

Lendo Dados

{
  "tool": "read-range",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range_name": "Sheet1!A1:E10"
  }
}

Escrevendo Dados

{
  "tool": "write-range",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range_name": "Sheet1!A1:C3",
    "values": [
      ["Name", "Age", "City"],
      ["Alice", "30", "New York"],
      ["Bob", "25", "San Francisco"]
    ]
  }
}

Adicionando Novos Dados

{
  "tool": "append-rows",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "range_name": "Sheet1!A:C",
    "values": [
      ["Charlie", "35", "Chicago"],
      ["Diana", "28", "Boston"]
    ]
  }
}

Atualizações em Lote

{
  "tool": "batch-update",
  "arguments": {
    "spreadsheet_id": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
    "updates": [
      {
        "range": "Sheet1!A1:B2",
        "values": [["Header1", "Header2"], ["Data1", "Data2"]]
      },
      {
        "range": "Sheet1!D1:E2",
        "values": [["Header3", "Header4"], ["Data3", "Data4"]]
      }
    ]
  }
}

🧪 Testes

Com o MCP Inspector

Teste o servidor usando o MCP Inspector:

npx @modelcontextprotocol/inspector uv run sheets \
  --creds-file-path /path/to/credentials.json \
  --token-path /path/to/tokens.json

Testes Manuais

  1. Crie uma planilha de teste
  2. Leia alguns dados para verificar a conectividade
  3. Escreva dados de teste para garantir que as permissões de escrita funcionem
  4. Experimente diferentes formatos de intervalo (notação A1, intervalos nomeados, etc.)

📊 Casos de Uso Comuns

Fluxos de Trabalho de Análise de Dados

1. Create spreadsheet for analysis
2. Import raw data via append-rows
3. Read data for processing
4. Write calculated results back
5. Generate reports and summaries

Gerenciamento de Conteúdo

1. Create content tracking spreadsheet
2. Append new content entries
3. Update status and metadata
4. Generate content reports

Gerenciamento de Projetos

1. Create project tracking sheet
2. Add tasks and milestones
3. Update progress and status
4. Generate project dashboards

Sincronização de Dados

1. Read data from external systems
2. Transform and validate data
3. Write to Google Sheets for sharing
4. Keep data synchronized across platforms

🔧 Recursos Avançados

Formatos de Intervalo Suportados

  • Notação A1: Sheet1!A1:C10
  • Intervalos nomeados: MyNamedRange
  • Colunas inteiras: Sheet1!A:C
  • Linhas inteiras: Sheet1!1:5
  • Intervalos abertos: Sheet1!A1:C

Tratamento de Erros

O servidor inclui tratamento abrangente de erros para:

  • Falhas de autenticação e renovação de token
  • Timeouts de rede e problemas de conectividade
  • IDs de planilha ou nomes de intervalo inválidos
  • Erros de permissão
  • Limites de cota da API
  • Entradas de dados malformadas

Considerações de Desempenho

  • Usa asyncio.to_thread para chamadas de API não bloqueantes
  • Suporta operações em lote para eficiência
  • Lida graciosamente com limites de taxa da API do Google Sheets
  • Otimizado para operações com dados pequenos e grandes

🔒 Segurança e Permissões

Escopos OAuth Necessários

  • https://www.googleapis.com/auth/spreadsheets - Acesso total ao Google Sheets

Boas Práticas de Segurança

  • Armazene credenciais com segurança
  • Use variáveis de ambiente para caminhos sensíveis
  • Implemente controles de acesso adequados
  • Rotacione tokens de acesso regularmente
  • Monitore o uso e as cotas da API

🤝 Contribuição e Extensão

Este servidor foi projetado para ser facilmente extensível. Melhorias comuns:

Recursos Adicionais

  • Operações de formatação (negrito, cores, bordas)
  • Suporte a fórmulas para células calculadas
  • Criação e gerenciamento de gráficos
  • Regras de formatação condicional
  • Restrições de validação de dados
  • Tabelas dinâmicas e resumos

Melhorias de Integração

  • Conectores de banco de dados para importação/exportação de dados
  • Importação/exportação de arquivos CSV/Excel
  • Recursos de colaboração em tempo real
  • Notificações via webhook para alterações
  • Pesquisa avançada e filtragem

Otimizações de Desempenho

  • Estratégias de cache para dados acessados com frequência
  • Suporte a streaming para grandes conjuntos de dados
  • Processamento paralelo para operações em massa
  • Pooling de conexões para cenários de alto throughput

📚 Referência da API

Limites da API do Google Sheets

  • 100 solicitações por 100 segundos por usuário
  • 1000 solicitações por 100 segundos (cota total)
  • Máximo de 10 milhões de células por planilha
  • Máximo de 200 planilhas por arquivo

Formatos de Resposta

Todas as ferramentas retornam respostas estruturadas com:

  • Indicadores de status (sucesso/erro)
  • Mensagens de erro detalhadas quando aplicável
  • Estatísticas de atualização para operações de escrita
  • Dados estruturados para operações de leitura

🆘 Solução de Problemas

Problemas Comuns

  1. Erros de Autenticação

    • Verifique o caminho do arquivo de credenciais
    • Verifique a configuração da tela de consentimento OAuth
    • Garanta que os escopos corretos estão configurados

  2. Erros de Permissão

    • Verifique as permissões de compartilhamento da planilha
    • Verifique se a planilha existe
    • Garanta que a conta tenha acesso de edição

  3. Erros de Intervalo

    • Valide o formato de notação A1
    • Verifique os nomes das planilhas quanto a erros de digitação
    • Verifique os limites do intervalo

  4. Cota Excedida

    • Implemente limitação de solicitações
    • Use operações em lote quando possível
    • Monitore o uso no Console do Google Cloud

Pronto para turbinar seus fluxos de trabalho do Google Sheets com operações automatizadas! 🚀