Google Sheets

Interaja com o Google Sheets usando um servidor MCP baseado em Python e o Google Apps Script.

Documentação

Google Sheets MCP Server

Servidor MCP em Python que permite ao Claude (Desktop ou qualquer cliente MCP) ler e escrever Google Sheets através de um Google Apps Script implantado como Web App.

O que faz

Leitura: células, intervalos e metadados de planilha.
Escrita: células e intervalos.
Utilidade: limpar intervalos, listar planilhas, testar a conexão.

Como funciona

Cliente MCP  →  servidor MCP (Python, local)  →  Apps Script Web App  →  Google Sheets

O Apps Script roda na sua própria conta do Google com sua sessão, então você não expõe credenciais OAuth nem tokens. O servidor MCP roda na sua máquina.

Segurança — leia antes de implantar

O Web App é publicado com "Executar como: eu" e acesso "Qualquer pessoa". Isso significa que a URL /exec é um endpoint sem autenticação: quem a conhecer pode ler e escrever sua planilha. Consequentemente:

Trate a URL do Web App como um segredo. Não a publique nem a faça commit.
Para algo além de testes, adicione um token compartilhado: faça o Apps Script exigir um parâmetro secreto e rejeitar as requisições que não o incluam.

A proteção real é que a URL seja privada (e, idealmente, um token); não há "várias camadas de segurança" além disso.

Requisitos

Python 3.8+
Um cliente MCP (por exemplo, Claude Desktop)
Conta do Google com acesso a Sheets e Apps Script

Instalação

git clone https://github.com/jona-mhw/google-sheets-mcp.git
cd google-sheets-mcp/mcp-server
pip install -r requirements.txt
cp .env.example .env
# edita .env y pon tu APPS_SCRIPT_URL

Apps Script

Em script.google.com crie um novo projeto.
Cole o conteúdo de apps-script/Code.gs.
Implantar → Nova implantação → Aplicativo web. Executar como: eu. Acesso: qualquer pessoa.
Copie a URL que termina em /exec: essa é a sua APPS_SCRIPT_URL.

Apps Script é gratuito até 6 horas de execução por dia, mais que suficiente para uso normal.

Configuração do cliente MCP

Arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-sheets": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/ruta/absoluta/a/google-sheets-mcp/mcp-server",
      "env": {
        "APPS_SCRIPT_URL": "https://script.google.com/macros/s/TU_SCRIPT_ID/exec",
        "DEBUG": "false"
      }
    }
  }
}

Reinicie o cliente.

Ferramentas

Ferramenta	Descrição
`read_cell`	lê uma célula
`write_cell`	escreve uma célula
`read_range`	lê um intervalo
`write_range`	escreve um intervalo
`clear_range`	limpa um intervalo
`list_sheets`	lista as planilhas
`test_connection`	testa a conexão

Problemas frequentes

No module named 'fastmcp': pip install -r requirements.txt.
APPS_SCRIPT_URL not configured: verifique se .env existe e se a URL está correta.
Claude não vê o MCP: cwd deve ser caminho absoluto; reinicie o cliente.

Licença

MIT. Veja LICENSE. Construído sobre FastMCP.