Google Sheets

🤔 O que é isto?

mcp-google-sheets é um servidor MCP baseado em Python que atua como uma ponte entre qualquer cliente compatível com MCP (como o Claude Desktop) e a API do Google Sheets. Ele permite que você interaja com suas planilhas do Google usando um conjunto definido de ferramentas, possibilitando automação poderosa e fluxos de manipulação de dados impulsionados por IA.

🚀 Início Rápido (Usando o uvx)

Basicamente, o servidor roda em uma única linha: uvx mcp-google-sheets@latest.

Este comando baixa automaticamente o código mais recente e o executa. Recomendamos sempre usar o @latest para garantir que você tenha a versão mais nova, com os recursos mais recentes e correções de bugs.

Consulte o Guia de Referência de IDs para obter mais informações sobre os IDs usados abaixo.

1. ☁️ Pré-requisito: Configuração do Google Cloud

   • Você deve configurar as credenciais do Google Cloud Platform e habilitar as APIs necessárias primeiro. Recomendamos fortemente o uso de uma Conta de Serviço.
   • ➡️ Vá para o guia de Configuração Detalhada do Google Cloud Platform abaixo.

2. 🐍 Instalar o uv

   • O uvx faz parte do uv, um instalador e resolvedor de pacotes Python rápido. Instale-o se ainda não tiver feito:

     # macOS / Linux
     curl -LsSf https://astral.sh/uv/install.sh | sh
     # Windows
     powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
     # Or using pip:
     # pip install uv
     

     Siga as instruções na saída do instalador para adicionar o uv ao seu PATH, se necessário.

3. 🔑 Definir as Variáveis de Ambiente Essenciais (Conta de Serviço Recomendada)

   • Você precisa informar ao servidor como autenticar. Defina estas variáveis no seu terminal:
   • (Linux/macOS)

     # Replace with YOUR actual path and folder ID from the Google Setup step
     export SERVICE_ACCOUNT_PATH="/path/to/your/service-account-key.json"
     export DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (CMD do Windows)

     set SERVICE_ACCOUNT_PATH="C:\path\to\your\service-account-key.json"
     set DRIVE_FOLDER_ID="YOUR_DRIVE_FOLDER_ID"
     

   • (PowerShell do Windows)

     $env:SERVICE_ACCOUNT_PATH = "C:\path\to\your\service-account-key.json"
     $env:DRIVE_FOLDER_ID = "YOUR_DRIVE_FOLDER_ID"
     

   • ➡️ Veja Autenticação Detalhada e Variáveis de Ambiente para outras opções (OAuth, CREDENTIALS_CONFIG).

4. 🏃 Executar o Servidor!

   • O uvx baixará e executará automaticamente a versão mais recente do mcp-google-sheets:

     uvx mcp-google-sheets@latest
     

   • O servidor iniciará e exibirá logs indicando que está pronto.

   • 💡 Dica Profissional: Use sempre o @latest para garantir que você obtenha a versão mais nova, com correções de bugs e recursos. Sem o @latest, o uvx pode usar uma versão antiga em cache.

5. 🔌 Conectar seu Cliente MCP

   • Configure seu cliente (ex.: Claude Desktop) para se conectar ao servidor em execução.
   • Dependendo do cliente que você usa, talvez não precise do passo 4, pois o cliente pode iniciar o servidor para você. Mas é uma boa prática executar o passo 4 de qualquer forma para garantir que tudo esteja configurado corretamente.
   • ➡️ Veja Uso com o Claude Desktop para exemplos.

6. ⚡ Opcional: Ativar a Filtragem de Ferramentas (Reduzir o Uso de Contexto)

   • Por padrão, todas as 19 ferramentas estão habilitadas (~13 mil tokens). Para reduzir o uso de contexto, habilite apenas as ferramentas que você precisa.
   • ➡️ Veja Filtragem de Ferramentas para detalhes.

Você está pronto! Comece a emitir comandos pelo seu cliente MCP.

✨ Principais Recursos

• Integração Perfeita: Conecta-se diretamente às APIs do Google Drive e do Google Sheets.
• Ferramentas Abrangentes: Oferece uma ampla gama de operações (CRUD, listagem, em lote, compartilhamento, formatação, etc.).
• Autenticação Flexível: Suporta Contas de Serviço (recomendado), OAuth 2.0 e injeção direta de credenciais via variáveis de ambiente.
• Implantação Fácil: Rode instantaneamente com o uvx (sem necessidade de instalação) ou clone para desenvolvimento usando uv.
• Pronto para IA: Projetado para uso com clientes compatíveis com MCP, permitindo interação em linguagem natural com planilhas.
• Filtragem de Ferramentas: Reduza o uso da janela de contexto habilitando apenas as ferramentas necessárias com a variável de ambiente --include-tools ou ENABLED_TOOLS.

🎯 Filtragem de Ferramentas (Reduzir o Uso de Contexto)

Problema: Por padrão, este servidor MCP expõe todas as 19 ferramentas, consumindo ~13.000 tokens antes mesmo de qualquer conversa começar. Se você precisa de apenas algumas ferramentas, isso desperdiça um espaço valioso da janela de contexto.

Solução: Use a filtragem de ferramentas para habilitar apenas as ferramentas que você realmente utiliza.

Como Ativar a Filtragem de Ferramentas

Você pode filtrar as ferramentas usando uma das seguintes opções:

1. Argumento de linha de comando --include-tools:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": [
           "mcp-google-sheets@latest",
           "--include-tools",
           "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         ],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json"
         }
       }
     }
   }
   

2. Variável de ambiente ENABLED_TOOLS:

   {
     "mcpServers": {
       "google-sheets": {
         "command": "uvx",
         "args": ["mcp-google-sheets@latest"],
         "env": {
           "SERVICE_ACCOUNT_PATH": "/path/to/credentials.json",
           "ENABLED_TOOLS": "get_sheet_data,update_cells,list_spreadsheets,list_sheets"
         }
       }
     }
   }
   

Nomes de Ferramentas Disponíveis

Ao filtrar, use estes nomes exatos de ferramentas (separados por vírgula, sem espaços):

Ferramentas Mais Comuns (subconjunto recomendado):

• get_sheet_data - Ler de planilhas
• update_cells - Escrever em planilhas
• list_spreadsheets - Encontrar planilhas
• list_sheets - Navegar entre abas

Todas as Ferramentas Disponíveis:

• add_columns
• add_rows
• batch_update
• batch_update_cells
• copy_sheet
• create_sheet
• create_spreadsheet
• find_in_spreadsheet
• get_multiple_sheet_data
• get_multiple_spreadsheet_summary
• get_sheet_data
• get_sheet_formulas
• list_folders
• list_sheets
• list_spreadsheets
• rename_sheet
• search_spreadsheets
• share_spreadsheet
• update_cells

Observação: Se nem --include-tools nem ENABLED_TOOLS forem especificados, todas as ferramentas estarão habilitadas (comportamento padrão).

🛠️ Ferramentas e Recursos Disponíveis

Este servidor expõe as seguintes ferramentas para interagir com o Google Sheets:

Consulte o Guia de Referência de IDs para obter mais informações sobre os IDs usados abaixo.

(Os parâmetros de entrada normalmente são strings, salvo indicação em contrário)

• list_spreadsheets: Lista as planilhas na pasta do Drive configurada (Conta de Serviço) ou acessíveis pelo usuário (OAuth).
  • folder_id (string opcional): ID da pasta do Google Drive para pesquisar. Obtenha pela URL. Se omitido, usa a pasta padrão configurada ou pesquisa 'Meu Drive'.
  • Retorna: Lista de objetos [{id: string, title: string}]
• create_spreadsheet: Cria uma nova planilha.
  • title (string): O título desejado para a planilha. Exemplo: "Relatório Trimestral Q4".
  • folder_id (string opcional): ID da pasta do Google Drive onde a planilha deve ser criada. Obtenha pela URL. Se omitido, usa a pasta padrão configurada ou a raiz.
  • Retorna: Objeto com informações da planilha, incluindo spreadsheetId, title e folder.
• get_sheet_data: Lê dados de um intervalo em uma planilha/aba.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • sheet (string): Nome da planilha/aba (ex.: "Sheet1").
  • range (string opcional): Notação A1 (ex.: 'A1:C10', 'Sheet1!B2:D'). Se omitido, lê toda a planilha/aba especificada por sheet.
  • include_grid_data (booleano opcional, padrão False): Se True, retorna dados completos da grade, incluindo formatação e metadados (muito maior). Se False, retorna apenas valores (mais eficiente).
  • Retorna: Se include_grid_data=True, dados completos da grade com metadados (resposta get). Se False, um objeto de resultado de valores da API de Valores (resposta values.get).
• get_sheet_formulas: Lê fórmulas de um intervalo em uma planilha/aba.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • sheet (string): Nome da planilha/aba (ex.: "Sheet1").
  • range (string opcional): Notação A1 (ex.: 'A1:C10', 'Sheet1!B2:D'). Se omitido, lê todas as fórmulas na planilha/aba especificada por sheet.
  • Retorna: Matriz 2D de fórmulas de células (matriz de matrizes) (resposta values.get).
• update_cells: Escreve dados em um intervalo específico. Substitui dados existentes.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • sheet (string): Nome da planilha/aba (ex.: "Sheet1").
  • range (string): Intervalo em notação A1 para escrever (ex.: 'A1:C3').
  • data (matriz de matrizes): Matriz 2D de valores a escrever. Exemplo: [[1, 2, 3], ["a", "b", "c"]].
  • Retorna: Objeto de resultado de atualização (resposta values.update).
• batch_update_cells: Atualiza vários intervalos em uma única chamada de API.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • sheet (string): Nome da planilha/aba (ex.: "Sheet1").
  • ranges (objeto): Dicionário mapeando strings de intervalo (notação A1) para matrizes 2D de valores. Exemplo: { "A1:B2": [[1, 2], [3, 4]], "D5": [["Hello"]] }.
  • Retorna: Resultado da operação (resposta values.batchUpdate).
• add_rows: Adiciona (insere) linhas vazias em uma planilha/aba em um índice especificado.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • sheet (string): Nome da planilha/aba (ex.: "Sheet1").
  • count (inteiro): Número de linhas vazias a inserir.
  • start_row (inteiro opcional, padrão 0): Índice de linha baseado em 0 para começar a inserir linhas. Se omitido, o padrão é 0 (insere no início).
  • Retorna: Resultado da operação (resposta batchUpdate).
• list_sheets: Lista todos os nomes de planilhas/abas dentro de uma planilha.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • Retorna: Lista de strings de nomes de planilhas/abas. Exemplo: ["Sheet1", "Sheet2"].
• create_sheet: Adiciona uma nova planilha/aba a uma planilha.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • title (string): Nome para a nova planilha/aba.
  • Retorna: Objeto de propriedades da nova planilha.
• get_multiple_sheet_data: Busca dados de vários intervalos em planilhas potencialmente diferentes em uma única chamada.
  • queries (matriz de objetos): Cada objeto precisa de spreadsheet_id, sheet e range. Exemplo: [{"spreadsheet_id": "abc", "sheet": "Sheet1", "range": "A1:B2"}, ...].
  • Retorna: Lista de objetos, cada um contendo os parâmetros de consulta e o data buscado ou um error. Cada data é uma resposta values.get.
• get_multiple_spreadsheet_summary: Obtém títulos, nomes de planilhas/abas, cabeçalhos e as primeiras linhas de várias planilhas.
  • spreadsheet_ids (matriz de strings): IDs das planilhas (das suas URLs).
  • rows_to_fetch (inteiro opcional, padrão 5): Quantas linhas (incluindo cabeçalho) visualizar. Exemplo: 5.
  • Retorna: Lista de objetos de resumo para cada planilha.
• share_spreadsheet: Compartilha uma planilha com usuários/e-mails e funções especificados.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • recipients (matriz de objetos): [{"email_address": "user@example.com", "role": "writer"}, ...]. Funções: reader, commenter, writer.
  • send_notification (booleano opcional, padrão True): Enviar notificações por e-mail aos destinatários.
  • Retorna: Dicionário com listas successes e failures.
• add_columns: Adiciona (insere) colunas vazias em uma planilha/aba em um índice especificado.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • sheet (string): Nome da planilha/aba (ex.: "Sheet1").
  • count (inteiro): Número de colunas vazias a inserir.
  • start_column (inteiro opcional, padrão 0): Índice de coluna baseado em 0 para começar a inserir. Se omitido, o padrão é 0 (insere no início).
  • Retorna: Resultado da operação (resposta batchUpdate).
• copy_sheet: Duplica uma planilha/aba de uma planilha para outra e opcionalmente a renomeia.
  • src_spreadsheet (string): ID da planilha de origem (da sua URL).
  • src_sheet (string): Nome da planilha/aba de origem (ex.: "Sheet1").
  • dst_spreadsheet (string): ID da planilha de destino (da sua URL).
  • dst_sheet (string): Nome desejado da planilha/aba na planilha de destino.
  • Retorna: Resultado das operações de cópia e renomeação opcional.
• rename_sheet: Renomeia uma planilha/aba existente.
  • spreadsheet (string): O ID da planilha (da sua URL).
  • sheet (string): Nome atual da planilha/aba (ex.: "Sheet1").
  • new_name (string): Novo nome da planilha/aba (ex.: "Transações").
  • Retorna: Resultado da operação (resposta batchUpdate).
• add_chart: Cria um gráfico em uma planilha do Google a partir de dados especificados.
  • spreadsheet_id (string): O ID da planilha (da sua URL).
  • sheet (string): Nome da planilha/aba que contém os dados (ex.: "Sheet1").
  • chart_type (string): Tipo de gráfico a criar. Opções: COLUMN (barras verticais), BAR (barras horizontais), LINE, AREA, PIE, SCATTER, COMBO, HISTOGRAM.
  • data_range (string): Intervalo em notação A1 para os dados do gráfico (ex.: "A1:C10"). A primeira linha é tratada como cabeçalho.
  • title (string opcional): Título do gráfico.
  • x_axis_label (string opcional): Rótulo para o eixo X (eixo inferior). Não aplicável a gráficos de pizza.
  • y_axis_label (string opcional): Rótulo para o eixo Y (eixo esquerdo). Não aplicável a gráficos de pizza.
  • position_x (inteiro opcional, padrão 0): Deslocamento de posição horizontal em pixels a partir do canto superior esquerdo.
  • position_y (inteiro opcional, padrão 0): Deslocamento de posição vertical em pixels a partir do canto superior esquerdo.
  • width (inteiro opcional, padrão 600): Largura do gráfico em pixels.
  • height (inteiro opcional, padrão 400): Altura do gráfico em pixels.
  • Retorna: Objeto de resultado com status de sucesso, ID do gráfico e detalhes da operação.

Recursos MCP:

• spreadsheet://{spreadsheet_id}/info: Obter metadados básicos sobre uma planilha do Google.
  • Retorna: String JSON com informações da planilha.

☁️ Configuração do Google Cloud Platform (Detalhada)

Esta configuração é obrigatória antes de executar o servidor.

1. Criar/Selecionar um projeto GCP: Vá para o Console do Google Cloud.
2. Habilitar APIs: Navegue até "APIs & Services" -> "Biblioteca". Pesquise e habilite:
   • Google Sheets API
   • Google Drive API
3. Configurar credenciais: Você precisa escolher um método de autenticação abaixo (Conta de Serviço é recomendada).

🔑 Autenticação e Variáveis de Ambiente (Detalhado)

O servidor precisa de credenciais para acessar as APIs do Google. Escolha um método:

Consulte o Guia de Referência de IDs para mais informações sobre os IDs usados abaixo.

Método A: Conta de Serviço (Recomendado para Servidores/Automação) ✅

• Por quê? Sem interface gráfica (não precisa de navegador), seguro, ideal para ambientes de servidor. Não expira facilmente.
• Passos:
  1. Criar Conta de Serviço: No Console GCP -> "IAM & Admin" -> "Service Accounts".
     • Clique em "+ CREATE SERVICE ACCOUNT". Dê um nome (ex.: mcp-sheets-service).
     • Conceda funções: Adicione a função Editor para acesso amplo, ou funções mais granulares (como roles/drive.file e funções específicas do Sheets) para permissões mais restritas.
     • Clique em "Done". Encontre a conta, clique em Ações (⋮) -> "Manage keys".
     • Clique em "ADD KEY" -> "Create new key" -> JSON -> "CREATE".
     • Baixe e armazene com segurança o arquivo de chave JSON.
  2. Criar e Compartilhar Pasta do Google Drive:
     • No Google Drive, crie uma pasta (ex.: "Planilhas Gerenciadas por IA").
     • Anote o ID da Pasta da URL: https://drive.google.com/drive/folders/THIS_IS_THE_FOLDER_ID.
     • Clique com o botão direito na pasta -> "Compartilhar" -> "Compartilhar".
     • Insira o e-mail da Conta de Serviço (do arquivo JSON client_email).
     • Conceda acesso de Editor. Desmarque "Notificar pessoas". Clique em "Compartilhar".
  3. Definir Variáveis de Ambiente:
     • SERVICE_ACCOUNT_PATH: Caminho completo para o arquivo de chave JSON baixado.
     • DRIVE_FOLDER_ID: O ID da pasta do Google Drive compartilhada. (Veja Início Rápido Ultra para exemplos específicos por sistema operacional)

Método B: OAuth 2.0 (Uso Interativo / Pessoal) 🧑‍💻

• Por quê? Para uso pessoal ou desenvolvimento local onde o login interativo no navegador é aceitável.
• Passos:
  1. Configurar Tela de Consentimento OAuth: No Console GCP -> "APIs & Services" -> "Tela de consentimento OAuth". Selecione "Externo", preencha as informações necessárias, adicione escopos (.../auth/spreadsheets, .../auth/drive), adicione usuários de teste se necessário.
  2. Criar ID de Cliente OAuth: No Console GCP -> "APIs & Services" -> "Credenciais". "+ CREATE CREDENTIALS" -> "OAuth client ID" -> Tipo: Aplicativo de desktop. Dê um nome. "CREATE". Baixe o JSON.
  3. Definir Variáveis de Ambiente:
     • CREDENTIALS_PATH: Caminho para o arquivo JSON de credenciais OAuth baixado (padrão: credentials.json).
     • TOKEN_PATH: Caminho para armazenar o token de atualização do usuário após o primeiro login (padrão: token.json). Deve ser gravável.

Método C: Injeção Direta de Credenciais (Avançado) 🔒

• Por quê? Útil em ambientes como Docker, Kubernetes ou CI/CD onde gerenciar arquivos é difícil, mas variáveis de ambiente são fáceis/seguras. Evita acesso ao sistema de arquivos.
• Como? Em vez de fornecer um caminho para o arquivo de credenciais, você fornece o conteúdo do arquivo, codificado em Base64, diretamente em uma variável de ambiente.
• Passos:
  1. Obtenha seu arquivo JSON de credenciais (chave de conta de serviço ou arquivo de ID de cliente OAuth). Vamos chamá-lo de your_credentials.json.
  2. Gere a string Base64:
     • (Linux/macOS): base64 -w 0 your_credentials.json
     • (Windows PowerShell):

       $filePath = "C:\path\to\your_credentials.json"; # Use actual path
       $bytes = [System.IO.File]::ReadAllBytes($filePath);
       $base64 = [System.Convert]::ToBase64String($bytes);
       $base64 # Copy this output
       

     • (Cuidado): Evite colar credenciais sensíveis em codificadores online não confiáveis.
  3. Defina a Variável de Ambiente:
     • CREDENTIALS_CONFIG: Defina esta variável para a string Base64 completa que você acabou de gerar.

       # Example (Linux/macOS) - Use the actual string generated
       export CREDENTIALS_CONFIG="ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb..."
       

Método D: Application Default Credentials (ADC) 🌐

• Por quê? Ideal para ambientes Google Cloud (GKE, Compute Engine, Cloud Run) e desenvolvimento local com gcloud auth application-default login. Nenhum arquivo de credenciais explícito é necessário.
• Como? Usa a cadeia de Application Default Credentials do Google para descobrir automaticamente credenciais de várias fontes.
• Ordem de busca do ADC:
  1. Variável de ambiente GOOGLE_APPLICATION_CREDENTIALS (caminho para a chave da conta de serviço) - variável padrão do Google
  2. Credenciais gcloud auth application-default login (desenvolvimento local)
  3. Conta de serviço anexada do servidor de metadados (GKE, Compute Engine, etc.)
• Configuração:
  • Desenvolvimento Local:
    1. Execute gcloud auth application-default login --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets,https://www.googleapis.com/auth/drive uma vez
    2. Defina um projeto de cota: gcloud auth application-default set-quota-project <project_id> (substitua <project_id> pelo ID do seu projeto Google Cloud)
  • Google Cloud: Anexe uma conta de serviço ao seu recurso de computação
  • Variável de Ambiente: Defina GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json (padrão do Google)
• Nenhuma variável de ambiente adicional é necessária - o ADC é usado automaticamente como fallback quando outros métodos falham.

Nota: GOOGLE_APPLICATION_CREDENTIALS é a variável de ambiente padrão oficial do Google, enquanto SERVICE_ACCOUNT_PATH é específica deste servidor MCP. Se você definir GOOGLE_APPLICATION_CREDENTIALS, o ADC a encontrará automaticamente.

Prioridade de Autenticação e Resumo

O servidor verifica as credenciais nesta ordem:

1. CREDENTIALS_CONFIG (conteúdo Base64)
2. SERVICE_ACCOUNT_PATH (caminho para o JSON da conta de serviço)
3. CREDENTIALS_PATH (caminho para o JSON OAuth) - aciona o fluxo interativo se o token estiver ausente/expirado
4. Application Default Credentials (ADC) - fallback automático

Resumo das Variáveis de Ambiente:

⚙️ Executando o Servidor (Detalhado)

Consulte o Guia de Referência de IDs para mais informações sobre os IDs usados abaixo.

Método 1: Usando uvx (Recomendado para Usuários)

Como mostrado no Início Rápido, esta é a maneira mais fácil. Defina as variáveis de ambiente e execute:

uvx mcp-google-sheets@latest

uvx cuida de buscar e executar o pacote temporariamente.

Método 2: Para Desenvolvimento (Clonando o Repositório)

Se você quiser modificar o código:

1. Clone: git clone https://github.com/yourusername/mcp-google-sheets.git && cd mcp-google-sheets (Use a URL real)
2. Defina as Variáveis de Ambiente: Conforme descrito acima.
3. Execute usando uv: (Usa o código local)

   uv run mcp-google-sheets
   # Or via the script name if defined in pyproject.toml, e.g.:
   # uv run start
   

Método 3: Docker (transporte SSE)

Execute o servidor em um contêiner usando o Dockerfile incluído:

# Build the image
docker build -t mcp-google-sheets .

# Run (SSE on port 8000)
# NOTE: Prefer CREDENTIALS_CONFIG (Base64 credentials content) in containers.
docker run --rm -p 8000:8000 ^
  -e HOST=0.0.0.0 ^
  -e PORT=8000 ^
  -e CREDENTIALS_CONFIG=YOUR_BASE64_CREDENTIALS ^
  -e DRIVE_FOLDER_ID=YOUR_DRIVE_FOLDER_ID ^
  mcp-google-sheets

• Use CREDENTIALS_CONFIG em vez de SERVICE_ACCOUNT_PATH dentro do Docker para evitar montar segredos como arquivos.
• O contêiner inicia com --transport sse e escuta em HOST/PORT. Aponte seu cliente MCP para http://localhost:8000 usando transporte SSE.

🔌 Uso com Claude Desktop

Adicione a configuração do servidor a claude_desktop_config.json em mcpServers. Escolha o bloco que corresponde à sua configuração:

Consulte o Guia de Referência de IDs para mais informações sobre os IDs usados abaixo.

⚠️ Notas Importantes:

• 🍎 Usuários macOS: use o caminho completo: "/Users/yourusername/.local/bin/uvx" em vez de apenas "uvx"

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "/Users/yourusername/.local/bin/uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/full/path/to/your/service-account-key.json",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_PATH": "/full/path/to/your/credentials.json",
        "TOKEN_PATH": "/full/path/to/your/token.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "CREDENTIALS_CONFIG": "ewogICJ0eXBlIjogInNlcnZpY2VfYWNjb3VudCIsCiAgInByb2plY3RfaWQiOiAi...",
        "DRIVE_FOLDER_ID": "your_shared_folder_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {
        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/service-account.json"
      }
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "command": "uvx",
      "args": ["mcp-google-sheets@latest"],
      "env": {}
    }
  }
}

{
  "mcpServers": {
    "mcp-google-sheets-local": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/mcp-google-sheets",
        "mcp-google-sheets"
      ],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/your/mcp-google-sheets/service_account.json",
        "DRIVE_FOLDER_ID": "your_drive_folder_id_here"
      }
    }
  }
}

💬 Exemplos de Prompts para Claude

Depois de conectado, experimente prompts como:

• "Liste todas as planilhas às quais tenho acesso." (ou "na minha pasta AI Managed Sheets")
• "Crie uma nova planilha intitulada 'Relatório de Vendas Trimestral Q3 2024'."
• "Na planilha 'Relatório de Vendas Trimestral', obtenha os dados da Sheet1 no intervalo A1 a E10."
• "Adicione uma nova aba chamada 'Resumo' à planilha com ID 1aBcDeFgHiJkLmNoPqRsTuVwXyZ."
• "Na minha planilha 'Tarefas do Projeto', na aba 'Tarefas', atualize a célula B2 para 'Em andamento'."
• "Anexe estas linhas à aba 'Log' na planilha XYZ: [['2024-07-31', 'Task A Completed'], ['2024-08-01', 'Task B Started']]"
• "Obtenha um resumo das planilhas 'Dados de Vendas' e 'Contagem de Estoque'."
• "Compartilhe a planilha 'Agenda de Férias da Equipe' com team@example.com como leitor e manager@example.com como escritor. Não envie notificações."
• "Crie um gráfico de colunas na minha planilha 'Relatório de Vendas' mostrando a receita mensal a partir dos dados no intervalo A1:B13."
• "Adicione um gráfico de pizza à aba 'Análise de Mercado' com dados de A1:B5 intitulado 'Participação de Mercado por Produto'."
• "Na planilha abc123, crie um gráfico de linhas na Sheet1 a partir do intervalo A1:C10 com o título 'Tendências de Crescimento' e rótulos 'Mês' e 'Receita'."

🆔 Guia de Referência de IDs

Use o seguinte guia de referência para encontrar os vários IDs mencionados ao longo da documentação:

Google Cloud Project ID:
  https://console.cloud.google.com/apis/dashboard?project=sheets-mcp-server-123456
                                                          └───── Project ID ─────┘

Google Drive Folder ID:
  https://drive.google.com/drive/u/0/folders/1xcRQCU9xrNVBPTeNzHqx4hrG7yR91WIa
                                             └────────── Folder ID ──────────┘

Google Sheets Spreadsheet ID:
  https://docs.google.com/spreadsheets/d/25_-_raTaKjaVxu9nJzA7-FCrNhnkd3cXC54BPAOXemI/edit
                                         └───────────── Spreadsheet ID ─────────────┘

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue para discutir bugs ou solicitações de recursos. Pull requests são apreciados.

📄 Licença

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

🙏 Créditos

• Construído com FastMCP.
• Inspirado por kazz187/mcp-google-spreadsheet.
• Usa as bibliotecas Google API Python Client.