sheets-mcp

Servidor MCP pessoal para Google Sheets + Apps Script. Publicado na Vercel, conecta em qualquer cliente MCP (Claude, ChatGPT, etc.) via OAuth de verdade — a pessoa clica "conectar", vai pra tela do Google, autoriza, e volta já funcionando.

URL do conector: https://google-planilhas-mcp.vercel.app/mcp

Ferramentas disponíveis

Related MCP server: mcp-gsheet

⚠️ Sobre o Apps Script: não tem como descobrir o ID sozinho

As ferramentas apps_script_* pedem um scriptId. Não existe forma automática de descobrir esse ID a partir do ID da planilha. Já tentamos (via Drive API, listando "filhos" do arquivo da planilha) e não funciona — scripts vinculados (container-bound) não aparecem nessa relação de parentesco pela API do Drive, mesmo com o escopo certo.

Isso significa que, sempre que alguém (ou a IA de alguém) for mexer num Apps Script vinculado a uma planilha pela primeira vez, precisa pegar o ID manualmente:

1. Abrir a planilha no Google Sheets.

2. Menu Extensões → Apps Script.

3. Ícone de engrenagem ⚙️ (Configurações do projeto).

4. Copiar o "ID do script".

Depois de pegar o ID uma vez, guarde-o (na conversa, num arquivo local, onde fizer sentido) — ele não muda, então só precisa fazer isso uma vez por projeto de script.

Scripts já conhecidos

Ao conectar um Apps Script novo (de outra planilha), adicione uma linha nessa tabela.

Como funciona (arquitetura)

• Autenticação do conector: servidor OAuth 2.1 próprio (/authorize, /token, /register, /.well-known/oauth-authorization-server), que por baixo dos panos redireciona pro login de verdade do Google. Depois que o Google autoriza, a gente guarda o refresh_token da conta Google no Vercel KV e emite um token de acesso MCP (que é só o MCP_SHARED_SECRET) pro cliente.

• Também dá pra conectar sem OAuth interativo, direto com o token na URL: https://google-planilhas-mcp.vercel.app/mcp?token=SEU_MCP_SHARED_SECRET

• lib/google.ts, lib/google-script.ts — montam clientes autenticados (Sheets API v4 e Apps Script API v1) usando o refresh token guardado no KV.

• app/[transport]/route.ts — expõe tudo isso como ferramentas MCP via @vercel/mcp-adapter.

Variáveis de ambiente (Vercel)

APIs que precisam estar ativadas no Google Cloud

• Google Sheets API

• Google Apps Script API

Escopos OAuth necessários (Tela de permissão OAuth)

• .../auth/spreadsheets

• .../auth/script.projects

Redirect URI cadastrada nas credenciais OAuth

https://google-planilhas-mcp.vercel.app/auth/spreadsheets — usada tanto pelo fluxo manual antigo (/api/auth/start) quanto pelo fluxo OAuth novo (/authorize). Se precisar trocar de domínio, atualize essa URI nas credenciais do Google Cloud também.

Limitações atuais

• Sem multiusuário: um único refresh token (uma única conta Google) fica guardado no KV. Pra abrir pra outras pessoas usarem, cada uma precisaria de um token separado — o design atual não separa isso.

• apps_script_update_content substitui todos os arquivos do projeto de uma vez; não dá pra editar um arquivo isolado sem mandar os outros junto.