Google Sheets

Servidor MCP Google Sheets

Um servidor Model Context Protocol (MCP) para integração com a API do Google Sheets. Permite ler, escrever e gerenciar documentos do Google Sheets diretamente do seu cliente MCP (ex.: Claude Code, Claude Desktop, Cursor, etc.).

Principais Recursos

• Integração Completa com o Google Sheets: Leia, escreva e gerencie planilhas
• Operações Avançadas: Operações em lote, formatação, gráficos e formatação condicional
• Autenticação Flexível: Suporte para credenciais baseadas em arquivo e em strings JSON
• Pronto para Produção: Construído com TypeScript, tratamento abrangente de erros e cobertura completa de testes

Requisitos

• Node.js v20 ou superior
• Projeto Google Cloud com a API Sheets habilitada
• Conta de serviço com arquivo de chave JSON
• npm

Começando

Instalação Rápida (Recomendado)

Adicione a seguinte configuração ao seu cliente MCP:

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

[!NOTE] Usar mcp-gsheets@latest garante que seu cliente MCP sempre utilize a versão mais recente do servidor MCP Google Sheets.

Configuração do Cliente MCP

claude mcp add mcp-gsheets npx mcp-gsheets@latest

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

Configuração do Google Cloud

1. Acesse o Console do Google Cloud
2. Crie um novo projeto ou selecione um existente
3. Habilite a API do Google Sheets:
   • Navegue até "APIs & Services" → "Library"
   • Pesquise por "Google Sheets API" e clique em "Enable"
4. Crie a Conta de Serviço:
   • Vá para "APIs & Services" → "Credentials"
   • Clique em "Create Credentials" → "Service Account"
   • Na lista de contas de serviço, clique nos três pontos na coluna Actions → Manage keys → Add key → Create new key → selecione o formato JSON
   • Baixe o arquivo de chave JSON
5. Compartilhe suas planilhas:
   • Abra sua planilha do Google
   • Clique em Compartilhar e adicione o e-mail da conta de serviço (do arquivo JSON)
   • Conceda permissões de "Editor"

Métodos Alternativos de Autenticação

Opção 1: Autenticação por String JSON

Em vez de usar um caminho de arquivo para as credenciais, você pode fornecer as credenciais da conta de serviço diretamente como uma string JSON. Isso é útil para ambientes conteinerizados, pipelines de CI/CD ou quando você deseja evitar o gerenciamento de arquivos de credenciais.

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_SERVICE_ACCOUNT_KEY": "{\"type\":\"service_account\",\"project_id\":\"your-project\",\"private_key_id\":\"...\",\"private_key\":\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\",\"client_email\":\"...@....iam.gserviceaccount.com\",\"client_id\":\"...\",\"auth_uri\":\"https://accounts.google.com/o/oauth2/auth\",\"token_uri\":\"https://oauth2.googleapis.com/token\",\"auth_provider_x509_cert_url\":\"https://www.googleapis.com/oauth2/v1/certs\",\"client_x509_cert_url\":\"...\"}"
      }
    }
  }
}

Observação: Ao usar GOOGLE_SERVICE_ACCOUNT_KEY:

• Todo o JSON deve estar em uma única linha
• Todas as aspas devem ser escapadas com barras invertidas
• Quebras de linha na chave privada devem ser representadas como \\n
• Se o JSON incluir um project_id, você pode omitir GOOGLE_PROJECT_ID

Opção 2: Autenticação por Chave Privada (Simplificada)

Para a abordagem mais amigável, você pode fornecer apenas a chave privada e o e-mail diretamente. Este é o método mais simples e requer apenas dois campos do JSON da sua conta de serviço:

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "npx",
      "args": ["-y", "mcp-gsheets@latest"],
      "env": {
        "GOOGLE_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCgR6bvMNOUHZ29\\n+YgbVHAXsT/s+L/jnXTCB193zikCzspSBSfxLu8VRDjkNq9WUoDxizTATzMFNvNf\\n...\\n-----END PRIVATE KEY-----\\n",
        "GOOGLE_CLIENT_EMAIL": "spreadsheet@your-project.iam.gserviceaccount.com"
      }
    }
  }
}

Observação: Ao usar GOOGLE_PRIVATE_KEY:

• Quebras de linha na chave privada devem ser representadas como \\n
• A chave privada deve incluir os marcadores -----BEGIN PRIVATE KEY----- e -----END PRIVATE KEY-----
• O e-mail do cliente deve ser o e-mail da conta de serviço do seu arquivo JSON
• GOOGLE_PROJECT_ID é opcional ao usar este método

Configuração de Desenvolvimento Local

Se você deseja desenvolver ou contribuir com este projeto, pode clonar e compilar localmente:

# Clone the repository
git clone https://github.com/freema/mcp-gsheets.git
cd mcp-gsheets

# Install dependencies
npm install

# Build the project
npm run build

Script de Configuração Interativo

Execute o script de configuração interativo para configurar seu cliente MCP local:

npm run setup

Isso irá:

• Guiá-lo pela configuração
• Detectar automaticamente sua instalação do Node.js (incluindo nvm)
• Encontrar a configuração do Claude Desktop
• Criar a configuração JSON adequada
• Opcionalmente, criar um arquivo .env para desenvolvimento

Configuração Manual Local

Se você preferir configuração manual com uma compilação local, adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "mcp-gsheets": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gsheets/dist/index.js"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/absolute/path/to/service-account-key.json"
      }
    }
  }
}

📦 Compilação e Desenvolvimento

Comandos de Desenvolvimento

# Development mode with hot reload
npm run dev

# Build for production
npm run build

# Type checking
npm run typecheck

# Clean build artifacts
npm run clean

# Run MCP inspector for debugging
npm run inspector

# Run MCP inspector in development mode
npm run inspector:dev

Executor de Tarefas (Alternativa)

Se você tiver o Task instalado:

# Install dependencies
task install

# Build the project
task build

# Run in development mode
task dev

# Run linter
task lint

# Format code
task fmt

# Run all checks
task check

Configuração de Desenvolvimento

1. Crie o arquivo .env para teste:

cp .env.example .env
# Edit .env with your credentials:
# GOOGLE_PROJECT_ID=your-project-id
# GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
# TEST_SPREADSHEET_ID=your-test-spreadsheet-id

2. Execute em modo de desenvolvimento:

npm run dev  # Watch mode with auto-reload

🎚️ Reduzindo o custo de contexto com conjuntos de ferramentas

Todas as 44 ferramentas juntas custam cerca de 9.900 tokens de contexto em cada sessão, antes de o modelo fazer qualquer coisa. A maioria dos fluxos de trabalho precisa de uma fração disso. GSHEETS_TOOLSETS limita quais ferramentas o servidor expõe:

{
  "mcpServers": {
    "gsheets": {
      "command": "npx",
      "args": ["mcp-gsheets"],
      "env": {
        "GOOGLE_PROJECT_ID": "your-project-id",
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
        "GSHEETS_TOOLSETS": "core,charts"
      }
    }
  }
}

Custo medido de tools/list:

Observações:

• O padrão não muda — deixe GSHEETS_TOOLSETS não definido e você terá todas as ferramentas, exatamente como antes.
• core está sempre incluído. GSHEETS_TOOLSETS=charts significa "gráficos além do núcleo", não "apenas gráficos" — sem o núcleo, o servidor não consegue ler uma célula.
• Um erro de digitação é um erro de inicialização, não uma lista de ferramentas silenciosamente menor.
• GSHEETS_READ_ONLY=true remove todas as ferramentas de escrita e pode ser combinado com GSHEETS_TOOLSETS. Ele é aplicado quando uma ferramenta é chamada, não apenas quando a lista é construída, então um cliente não pode escrever nomeando uma ferramenta oculta.

Todas as ferramentas também carregam anotações MCP (readOnlyHint, destructiveHint, idempotentHint), para que os clientes possam pular prompts de confirmação em leituras e avisar antes de operações destrutivas.

📋 Ferramentas Disponíveis

Leitura de Dados

Escrita de Dados

Gerenciamento de Planilhas

Formatação de Células

Tabelas Nativas

Gráficos

Ferramentas de Leitura / Snapshot

🔧 Qualidade do Código

Linting

# Run ESLint
npm run lint

# Fix auto-fixable issues
npm run lint:fix

Formatação

# Check formatting with Prettier
npm run format:check

# Format code
npm run format

Verificação de Tipos

# Run TypeScript type checking
npm run typecheck

❗ Solução de Problemas

Problemas Comuns

"Falha na autenticação"

• Se estiver usando autenticação baseada em arquivo: verifique se o caminho da chave JSON é absoluto e correto
• Se estiver usando autenticação por string JSON: certifique-se de que o JSON esteja devidamente escapado e válido
• Se estiver usando autenticação por chave privada: verifique se a chave privada inclui marcadores BEGIN/END e se as quebras de linha são escapadas como \\n
• Verifique se GOOGLE_CLIENT_EMAIL é um e-mail válido de conta de serviço
• Verifique se GOOGLE_PROJECT_ID corresponde ao seu projeto (ou está incluído no JSON para autenticação JSON completa)
• Certifique-se de que a API Sheets esteja habilitada

"Permissão negada"

• Compartilhe a planilha com o e-mail da conta de serviço
• A conta de serviço precisa do papel de "Editor"
• Verifique o e-mail no arquivo JSON (campo client_email)

"Planilha não encontrada"

• Verifique o ID da planilha na URL
• Formato: https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

Problemas de Conexão MCP

• Certifique-se de estar usando a versão compilada (dist/index.js)
• Verifique se o caminho do Node.js está correto na configuração do Claude Desktop
• Procure por erros nos logs do Claude Desktop
• Use npm run inspector para depurar

🔍 Encontrando IDs

ID da Planilha

A partir da URL:

https://docs.google.com/spreadsheets/d/1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms/edit
                                        ↑ This is the spreadsheet ID

ID da Planilha (Aba)

Use sheets_get_metadata para listar todas as planilhas (abas) com seus IDs.

📝 Dicas

1. Sempre teste com uma cópia dos seus dados
2. Use operações em lote para melhor desempenho
3. Defina permissões adequadas (somente leitura vs edição)
4. Verifique os limites de taxa para operações grandes
5. Use sheets_check_access para verificar permissões antes das operações

📘 Detalhes das Ferramentas

sheets_get_sheet_structure

Retorna metadados estruturais/dimensionais leves de uma planilha sem nenhum dado por célula. Muito mais rápido e econômico que sheets_get_full_sheet_snapshot quando você só precisa de informações de layout.

Parâmetros:

• spreadsheetId (obrigatório): O ID da planilha
• sheetName (obrigatório): Nome da planilha (aba)

Retorna: sheetName, sheetId, sheetIndex, tabColor, tabColorStyle, dimensions (rowCount, columnCount), frozen (rowCount, columnCount), columnWidths (matriz de tamanhos em pixels), rowHeights (matriz de tamanhos em pixels), hiddenColumns (índices baseados em 0), hiddenRows (índices baseados em 0), mergeCount, merges (matriz em notação A1)

sheets_get_formatting_compact

Ler a formatação de células de um intervalo e retorná-la como pares compactos A1Range → formato. Células adjacentes com formatação idêntica são agrupadas em intervalos retangulares (codificados por comprimento de execução), reduzindo a saída em mais de 90 % em comparação com dados por célula.

Parâmetros:

• spreadsheetId (obrigatório): O ID da planilha
• sheetName (obrigatório): Nome da planilha (aba)
• range (obrigatório): Intervalo sem prefixo da planilha, ex.: "A1:Z85"
• useEffectiveFormat (opcional): false (padrão) = userEnteredFormat (apenas substituições explícitas, saída menor); true = effectiveFormat (todos os padrões herdados)
• fields (opcional): Matriz de nomes de campos de formato a incluir, ex.: ["backgroundColor", "textFormat", "borders"]

Retorna: { range, formatType, rangeCount, data: { "A1:C3": { backgroundColor: {...} }, ... } }

Campos suportados: backgroundColor, backgroundColorStyle, textFormat, horizontalAlignment, verticalAlignment, wrapStrategy, textRotation, numberFormat, padding, borders

sheets_get_full_sheet_snapshot

Ferramenta mestre de chamada única que retorna todos os metadados estruturais e de formatação em uma única chamada de API.

Parâmetros:

• spreadsheetId (obrigatório): O ID da planilha
• sheetName (obrigatório): Nome da planilha (aba)
• includeFormattingRange (opcional): Se fornecido (ex.: "A1:Z100"), a formatação por célula é incluída na resposta
• useEffectiveFormat (opcional): Use effectiveFormat em vez de userEnteredFormat ao incluir formatação de células (padrão: false)
• fields (opcional): Matriz de nomes de campos de formato a retornar, ex.: ["backgroundColor", "textFormat"] — reduz o tamanho da transferência da API e o tamanho da resposta
• compactMode (opcional): Quando true, células adjacentes idênticas são agrupadas em intervalos retangulares (RLE). Reduz uma planilha típica de 85×28 de ~60 000 linhas para ~500 linhas (padrão: false)

sheets_insert_rows

Inserir novas linhas em uma posição específica em uma planilha, com dados opcionais.

Parâmetros:

• spreadsheetId (obrigatório): O ID da planilha
• range (obrigatório): Ponto de ancoragem em notação A1 onde as linhas serão inseridas (ex.: "Sheet1!A5")
• rows (opcional): Número de linhas a inserir (padrão: 1)
• position (opcional): 'BEFORE' ou 'AFTER' em relação à linha de ancoragem (padrão: 'BEFORE')
• inheritFromBefore (opcional): Se deve herdar a formatação da linha anterior (padrão: false)
• values (opcional): Matriz 2D de valores para preencher as novas linhas inseridas
• valueInputOption (opcional): 'RAW' ou 'USER_ENTERED' (padrão: 'USER_ENTERED')

Exemplos:

// Insert 1 empty row before row 5
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A5"
}

// Insert 3 rows after row 10 with data
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!A10",
  "rows": 3,
  "position": "AFTER",
  "values": [
    ["John", "Doe", "john@example.com"],
    ["Jane", "Smith", "jane@example.com"],
    ["Bob", "Johnson", "bob@example.com"]
  ]
}

sheets_delete_columns

Excluir uma ou mais colunas de uma planilha usando um intervalo A1 de coluna inteira.

Parâmetros:

• spreadsheetId (obrigatório): O ID da planilha
• range (obrigatório): Intervalo A1 de coluna inteira a excluir (ex.: "Sheet1!B:D" ou "Sheet1!C:C")

Exemplos:

// Delete columns B through D from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!B:D"
}

// Delete a single column from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "C:C"
}

sheets_delete_rows

Excluir uma ou mais linhas de uma planilha usando um intervalo A1 de linha inteira.

Parâmetros:

• spreadsheetId (obrigatório): O ID da planilha
• range (obrigatório): Intervalo A1 de linha inteira a excluir (ex.: "Sheet1!2:4" ou "Sheet1!3:3")

Exemplos:

// Delete rows 2 through 4 from Sheet1
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "Sheet1!2:4"
}

// Delete a single row from the first sheet
{
  "spreadsheetId": "your-spreadsheet-id",
  "range": "3:3"
}

📋 Changelog

Consulte CHANGELOG.md para obter uma lista de alterações em cada versão.

🤝 Contribuição

1. Faça um fork do repositório
2. Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
3. Execute testes e linting (npm run check)
4. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
5. Envie para a branch (git push origin feature/amazing-feature)
6. Abra um Pull Request

👤 Autor

Tomáš Grásl - tomasgrasl.cz

📄 Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.