Google Sheets MCP

Google Sheets MCP

Um servidor Model Context Protocol (MCP) que dá ao Claude (e a outros clientes MCP) acesso de leitura/escrita a qualquer planilha do Google via OAuth.

Ferramentas

Ferramenta	Descrição
read_sheet	Ler dados de qualquer intervalo em uma planilha
write_sheet	Escrever ou atualizar dados em uma planilha
append_rows	Adicionar novas linhas a uma planilha
get_sheet_info	Obter nomes de planilhas, contagens de linhas e contagens de colunas
clear_range	Limpar um intervalo de células

Todas as ferramentas aceitam uma URL completa do Google Sheets ou um ID de planilha simples.

---

Pré-requisitos

• Node.js 18+
• Uma conta do Google
• Um projeto do Google Cloud (gratuito)

---

Configuração

1. Clone o repositório

git clone https://github.com/generalist-club/google-sheets-mcp.git
cd google-sheets-mcp
npm install

2. Crie um projeto do Google Cloud e credenciais OAuth

1. Acesse o Google Cloud Console
2. Crie um novo projeto (ou selecione um existente)
3. Ative a Google Sheets API e a Google Drive API:
   • Navegue até APIs e serviços → Biblioteca
   • Pesquise e ative ambas as APIs
4. Crie credenciais OAuth:
   • Navegue até APIs e serviços → Credenciais
   • Clique em Criar credenciais → ID do cliente OAuth
   • Tipo de aplicativo: Aplicativo para desktop
   • Baixe o arquivo JSON
5. Renomeie o arquivo baixado para credentials.json e coloque-o na raiz do projeto

3. Autentique

Execute o script de autenticação para gerar seu token:

node auth.js

Ele exibirá uma URL. Abra-a no seu navegador, autorize o aplicativo e cole o código de volta no terminal. Isso cria um arquivo token.json localmente — mantenha-o em segredo.

Atualização do token: O servidor atualiza automaticamente o token de acesso quando ele expira. Você só deve precisar executar auth.js uma vez.

4. Configure o Claude Desktop (ou qualquer cliente MCP)

Adicione este servidor à configuração do seu Claude Desktop em ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "google-sheets": {
      "command": "node",
      "args": ["/absolute/path/to/google-sheets-mcp/index.js"]
    }
  }
}

Substitua /absolute/path/to/google-sheets-mcp pelo caminho real na sua máquina.

Reinicie o Claude Desktop. As cinco ferramentas do Google Sheets estarão agora disponíveis.

---

Exemplos de uso

Depois de conectado, você pode pedir ao Claude coisas como:

• "Leia os dados desta planilha: https://docs.google.com/spreadsheets/d/..."
• "Adicione uma nova linha com a data de hoje e 42 na Sheet1"
• "Quais planilhas estão neste arquivo e quantas linhas cada uma tem?"
• "Limpe o intervalo B2:D10 na minha planilha"

---

Notas de segurança

• credentials.json e token.json são excluídos do git via .gitignore — nunca os envie para o repositório
• O token OAuth é armazenado localmente e concede acesso apenas à sua própria conta do Google
• Escopos solicitados: spreadsheets (leitura/escrita) e drive.readonly (para resolver metadados da planilha)

---

Licença

MIT