mcp-google-sheets

Google Sheets MCP

Inglês | Русский

A1 Google Sheets MCP permite que um aplicativo de IA trabalhe com o Google Sheets em linguagem natural. Encontre uma planilha, leia seus dados, escreva e acrescente linhas, molde planilhas e formatação, crie gráficos e compartilhe o resultado.

Ele usa a API do Google Sheets com sua conta do Google. Ele separa a leitura da escrita, mantém operações destrutivas explícitas e deixa claros os limites da API do Sheets, em vez de sugerir que toda tarefa de planilha é possível.

• 26 ferramentas. Pesquise e crie planilhas, leia e escreva intervalos, gerencie planilhas, formatação, validação de dados, intervalos protegidos, formatação condicional, tabelas estruturadas, gráficos e acesso.
• Conecta-se a partir da conversa. Diga "conectar Google Sheets": o servidor guia você pelo cliente OAuth, captura o redirecionamento do Google em 127.0.0.1 com PKCE e guarda os tokens ele mesmo — sem arquivos de configuração, sem reiniciar.
• Escritas são deliberadas. Uma escrita nunca é repetida após uma falha ambígua — uma adição repetida duplicaria linhas — e ferramentas destrutivas são marcadas para que seu cliente de IA possa perguntar antes.
• Somente Sheets. O Drive é uma dependência interna apenas para pesquisa e compartilhamento de planilhas; não há ferramenta genérica do Drive, e raw_request não pode acessar o Drive.
• Escopos mínimos do Google. spreadsheets cobre todas as ferramentas do Sheets; um escopo do Drive é necessário apenas para pesquisa e compartilhamento de planilhas.

Comece com uma pergunta somente de leitura:

Encontre a planilha de orçamento trimestral e resuma o que cada uma de suas abas contém.

Conectar o servidor · Explorar casos de uso · Abrir documentação técnica

Veja funcionando em um minuto

Você: Mostre-me a estrutura da planilha de relatório de vendas — suas abas, tamanhos e linhas congeladas.

Assistente: Mostra as abas com seus tamanhos, cabeçalhos congelados e os objetos nelas. Nada muda.

Você: Prepare uma aba "Março" como cópia de "Fevereiro" e limpe os números, mantendo o layout.

Assistente: Mostra o plano — duplicar a aba, renomeá-la e limpar os intervalos de dados — e então pede confirmação antes de alterar qualquer coisa.

Você: Confirmo.

Assistente: Duplica a aba e limpa os valores. Formatação, validação de dados e linhas congeladas permanecem.

Conteúdo

• Início rápido
• O que você pode pedir que ele faça
• Como uma planilha muda
• O que pode mudar
• Obtendo acesso
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa do Node.js 20+ e de uma conta do Google. Credenciais não são necessárias na instalação — o servidor se conecta a partir da conversa.

1. Adicione o servidor ao seu aplicativo de IA.
2. Diga "conectar Google Sheets": o assistente guia você pela criação do cliente OAuth e aprovação do acesso sem editar arquivos de configuração.
3. Faça a pergunta somente de leitura acima.

codex mcp add google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-sheets \
  -- npx -y @a1-x-tech/mcp-google-sheets@latest

claude mcp list

{
  "mcpServers": {
    "google-sheets": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

{
  "servers": {
    "google-sheets": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-sheets@latest"]
    }
  }
}

O que você pode pedir que ele faça

Encontrar e ler dados

• Encontre a planilha mais recente com "orçamento" no nome e mostre sua estrutura.
• Leia 'Q3'!A1:F50 e resuma os totais.
• Mostre as fórmulas por trás da aba Resumo.

Atualizar os números

• Escreva esta tabela em Sheet1!A1, incluindo fórmulas.
• Acrescente os números de hoje como uma nova linha do registro.
• Atualize vários intervalos em um único lote, ou limpe um intervalo de rascunho mantendo sua formatação.

Moldar e apresentar

• Adicione uma aba "Março", congele a linha de cabeçalho e deixe-a em negrito.
• Destaque valores negativos em vermelho com formatação condicional e adicione bordas.
• Crie um gráfico de colunas da receita por mês em sua própria aba.
• Transforme os dados em uma tabela estruturada e adicione um menu suspenso com validação de dados.

Proteger e compartilhar

• Proteja a linha de totais para que apenas eu possa editá-la.
• Dê a um colega acesso de edição e a todos os outros somente leitura.
• Mostre quem tem acesso atualmente ao arquivo.

Como uma planilha muda

1. Ferramentas de valores endereçam células em notação A1 ('Sheet name'!A1:C10); ferramentas estruturais (abas, formatação, regras, tabelas, gráficos) endereçam um sheetId numérico com índices baseados em 0. get_spreadsheet fornece os ids — títulos de abas não são endereços.
2. Uma escrita sobrescreve seu intervalo; append_values adiciona linhas após a última linha de dados; uma célula null é ignorada, não limpa.
3. clear_values esvazia valores e fórmulas, mas mantém formatação, validação de dados, notas e mesclagens. Não há desfazer pela API — excluir uma aba, linhas ou colunas destrói seus dados.
4. Ferramentas em lote carregam vários intervalos ou solicitações em uma única chamada e contam uma vez contra a cota; um batchUpdate é atômico — todas as suas solicitações são aplicadas ou nenhuma é.

Alguns recursos de planilha não têm ferramenta dedicada: células mescladas, intervalos nomeados, faixas, filtros, slicers, localizar-e-substituir e regras de formatação condicional com gradiente passam por raw_request, que é limitado à origem da API do Sheets. Uma nova planilha vai para a raiz do Meu Drive — movê-la para uma pasta não é coberto, e manage_permissions não pode transferir propriedade.

O que pode mudar

O cliente de IA controla os avisos de confirmação. O servidor marca ferramentas de leitura, escrita e destrutivas para que o cliente possa distinguir uma inspeção de uma alteração ao vivo.

Obtendo acesso

O Google Sheets exige OAuth 2.0; uma chave de API não é suficiente. Há dois caminhos, e o primeiro não precisa de arquivos de configuração.

Conectar pelo chat (recomendado)

Diga "conectar Google Sheets" e o assistente executa o fluxo com você:

1. setup_instructions imprime a lista de verificação: criar ou selecionar um projeto do Google Cloud, ativar a API Google Sheets, configurar a tela de consentimento e criar um cliente OAuth de Aplicativo de desktop.
2. Baixe o JSON desse cliente ("Baixar JSON") e dê ao assistente o caminho — set_client o armazena somente para o proprietário. O segredo nunca passa pela conversa.
3. start_login retorna um link de consentimento do Google. Abra-o nesta máquina e aprove; o código volta para um ouvinte de uso único em 127.0.0.1 (PKCE), nunca pelo chat.
4. finish_login troca o código e salva os tokens em ~/.config/mcp-google-sheets/credentials.json (modo 0600).

Os tokens são relidos a cada chamada, então a conexão funciona imediatamente — sem reiniciar o aplicativo de IA. auth_status mostra o que está conectado, logout revoga e exclui.

Variáveis de ambiente (CI, instalações não assistidas)

1. Crie ou selecione um projeto do Google Cloud e ative a API Google Sheets. Ative também a API Google Drive se quiser pesquisa e compartilhamento de planilhas.

2. Configure a tela de consentimento OAuth e crie um cliente OAuth de Aplicativo de desktop.

3. Autorize a conta do Google que possui ou pode editar as planilhas. O OAuth 2.0 Playground pode obter o token de atualização quando Usar minhas próprias credenciais OAuth estiver ativado.

4. Solicite o escopo mínimo:

   https://www.googleapis.com/auth/spreadsheets
   

   Ele cobre todas as ferramentas do Sheets. Apenas search_spreadsheets e manage_permissions precisam de um escopo do Drive adicional: https://www.googleapis.com/auth/drive, ou drive.readonly apenas para pesquisa, ou drive.file para arquivos criados por este aplicativo.

Tokens de atualização OAuth em modo de teste podem expirar após sete dias. Publique o aplicativo OAuth, ou use um aplicativo Interno em um domínio do Workspace, quando precisar de acesso de longa duração. Trate o segredo do cliente e o token de atualização como senhas.

Configuração

Toda variável é opcional — sem nenhuma delas o servidor se conecta pelo chat.

* Forneça o trio OAuth ou um token de acesso. Sem credenciais, o servidor ainda inicia e lista suas ferramentas; a primeira chamada nomeia as variáveis a definir.

Dados, limites e trabalho em segundo plano

• As solicitações vão para o Google. O servidor local atualiza os tokens OAuth do Google e chama a API do Sheets — e, apenas para pesquisa e compartilhamento de planilhas, a API do Drive. Sua telemetria anônima contém um ID de instalação, versão do pacote, cliente de IA e versões de plataforma, e nomes de ferramentas — nunca tokens OAuth, dados de planilhas, argumentos de ferramentas ou prompts. Defina ASKADS_TELEMETRY=0 para optar por não participar.
• O Google aplica cotas por minuto. Os limites documentados são 300 leituras e 300 gravações por minuto por projeto, e 60 de cada por usuário; uma chamada em lote conta uma vez, independentemente de quantos intervalos ou solicitações ela carrega. Uma planilha contém no máximo 10.000.000 de células. Em 429, o servidor usa backoff; leituras também são repetidas após erros de rede e 5xx, enquanto gravações não são reproduzidas após uma falha incerta.
• Não há polling em segundo plano. O servidor é executado apenas quando chamado. Se seu aplicativo de IA suportar tarefas agendadas, ele pode verificar uma planilha periodicamente.

Documentação técnica

• Catálogo de capacidades do MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas e entradas
• Documentação de desenvolvimento
• Documentação de publicação
• Referência da API do Google Sheets

Suporte

Encontrou um bug ou precisa de um cenário? Crie um problema ou escreva no Telegram.

Você chegou ao fim!