Ultimate Google Docs & Drive MCP Server

Interaja com Google Docs e Google Drive para criação, edição de documentos e gerenciamento de arquivos.

Documentação

Google Docs, Sheets, Drive, Gmail & Calendar MCP Server

Demo Animation

Conecte o Claude Desktop, Cursor ou qualquer cliente MCP aos seus Google Docs, Google Sheets, Google Drive, Gmail e Google Calendar.

Início Rápido

1. Criar um Cliente OAuth do Google Cloud

Acesse o Google Cloud Console
Crie ou selecione um projeto
Ative as APIs Google Docs API, Google Sheets API, Google Drive API, Gmail API e Google Calendar API
Configure a tela de consentimento OAuth (Externa, adicione seu e-mail como usuário de teste e adicione os escopos gmail.modify e calendar.events junto com os escopos de Docs/Sheets/Drive)
Crie um ID de cliente OAuth (tipo aplicativo de desktop)
Copie o Client ID e o Client Secret da tela de confirmação

Precisa de mais detalhes? Veja as instruções passo a passo no final desta página.

2. Autorizar

GOOGLE_CLIENT_ID="your-client-id" \
GOOGLE_CLIENT_SECRET="your-client-secret" \
npx -y @a-bonus/google-docs-mcp auth

Isso abre seu navegador para autorização do Google. Após aprovar, o token de atualização é salvo em ~/.config/google-docs-mcp/token.json.

3. Adicionar ao Seu Cliente MCP

Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

O servidor inicia automaticamente quando seu cliente MCP precisa dele.

Implantação Remota (Cloud Run)

Implante uma vez para sua equipe — sem necessidade de instalações locais. O servidor usa MCP OAuth 2.1, então seu cliente MCP lida com a autenticação automaticamente.

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

Depois, cada usuário apenas adiciona a URL ao seu cliente MCP — sem npx, sem tokens, sem configuração local:

{
  "mcpServers": {
    "google-docs": {
      "type": "streamableHttp",
      "url": "https://your-service.run.app/mcp"
    }
  }
}

Seu cliente MCP solicitará o login do Google na primeira conexão. Veja Implantação Remota para detalhes.

O Que Ele Pode Fazer?

Ferramentas para Google Docs, Sheets e Drive:

Google Docs

Ferramenta	Descrição
`readDocument`	Ler conteúdo como texto simples, JSON ou markdown
`appendText`	Adicionar texto a um documento
`insertText`	Inserir texto em uma posição específica
`deleteRange`	Remover conteúdo por intervalo de índice
`modifyText`	Substituir, prefixar ou transformar texto em um documento
`findAndReplace`	Localizar e substituir texto em um documento
`findElement`	Localizar ocorrências de texto (com intervalos de índice) ou listar parágrafos/tabelas
`listTabs`	Listar todas as guias em um documento com várias guias
`addTab`	Adicionar uma nova guia a um documento
`renameTab`	Renomear uma guia do documento
`replaceDocumentWithMarkdown`	Substituir todo o conteúdo do documento a partir de markdown
`replaceRangeWithMarkdown`	Substituir um intervalo específico com conteúdo markdown
`appendMarkdown`	Adicionar conteúdo formatado em markdown
`applyTextStyle`	Negrito, itálico, cores, tamanho da fonte, links
`applyParagraphStyle`	Alinhamento, espaçamento, recuo
`insertTable`	Criar uma tabela vazia
`insertTableWithData`	Criar uma tabela pré-preenchida com dados
`insertPageBreak`	Inserir quebras de página
`insertSectionBreak`	Inserir quebra de seção (NEXT_PAGE ou CONTINUOUS)
`updateSectionStyle`	Atualizar estilo da seção: inverter orientação, margens
`insertImage`	Inserir imagens de URLs ou arquivos locais

Comentários

Ferramenta	Descrição
`listComments`	Ver todos os comentários com autor e data
`getComment`	Obter um comentário específico com respostas
`addComment`	Criar um comentário ancorado a um texto
`replyToComment`	Responder a um comentário existente
`resolveComment`	Marcar um comentário como resolvido
`deleteComment`	Remover um comentário

Google Sheets

Ferramenta	Descrição
`readSpreadsheet`	Ler dados de um intervalo (notação A1)
`writeSpreadsheet`	Escrever dados em um intervalo
`batchWrite`	Escrever em vários intervalos em uma única chamada
`appendRows`	Adicionar linhas a uma planilha
`clearRange`	Limpar valores de células
`createSpreadsheet`	Criar uma nova planilha
`addSheet`	Adicionar uma planilha/aba
`deleteSheet`	Remover uma planilha/aba
`duplicateSheet`	Duplicar uma planilha dentro da mesma pasta de trabalho
`copySheetTo`	Copiar uma planilha para outra pasta de trabalho
`renameSheet`	Renomear uma planilha/aba
`getSpreadsheetInfo`	Obter metadados e lista de planilhas
`listSpreadsheets`	Localizar planilhas
`formatCells`	Negrito, cores, alinhamento, alinhamento vertical, estratégia de quebra em intervalos
`copyFormatting`	Copiar formatação de um intervalo para outro
`readCellFormat`	Ler detalhes de formatação de um intervalo de células
`setCellBorders`	Definir bordas por lado (superior/inferior/esquerda/direita/interna) com estilo e cor
`freezeRowsAndColumns`	Fixar linhas/colunas de cabeçalho
`setDropdownValidation`	Adicionar/remover listas suspensas em células
`setColumnWidths`	Definir larguras de colunas em pixels
`setRowHeights`	Definir alturas de linhas em pixels
`autoResizeColumns`	Ajustar automaticamente larguras de colunas ao conteúdo
`autoResizeRows`	Ajustar automaticamente alturas de linhas ao conteúdo
`protectRange`	Bloquear um intervalo ou planilha inteira (somente aviso ou bloqueio total)
`addConditionalFormatting`	Adicionar uma regra de formatação condicional
`getConditionalFormatting`	Listar regras de formatação condicional com seu índice (JSON)
`deleteConditionalFormatting`	Excluir regras de formatação condicional por índice
`groupRows`	Agrupar linhas para seções recolhíveis
`ungroupAllRows`	Remover todos os agrupamentos de linhas
`createSheetsComment`	Criar um comentário na planilha, opcionalmente com link direto para célula
`createSheetsCellNote`	Criar uma nota nativa de célula anexada a uma célula ou intervalo
`insertChart`	Criar um gráfico a partir de dados
`deleteChart`	Remover um gráfico

Tabelas do Google Sheets

Ferramenta	Descrição
`createTable`	Criar uma nova tabela nomeada com tipos de coluna
`listTables`	Listar todas as tabelas em uma planilha ou aba
`getTable`	Obter metadados detalhados da tabela por nome ou ID
`deleteTable`	Excluir uma tabela (opcionalmente limpar dados)
`updateTableRange`	Modificar dimensões da tabela (adicionar/remover linhas/colunas)
`appendTableRows`	Adicionar linhas a uma tabela (inserção ciente da tabela)

Google Drive

Ferramenta	Descrição
`listDocuments`	Listar documentos, opcionalmente filtrados por data
`searchDocuments`	Pesquisar por nome ou conteúdo
`getDocumentInfo`	Obter metadados do documento
`createDocument`	Criar um novo documento
`createDocumentFromTemplate`	Criar a partir de um modelo existente
`createFolder`	Criar uma pasta
`listFolderContents`	Listar conteúdos da pasta
`getFolderInfo`	Obter metadados da pasta
`moveFile`	Mover um arquivo para outra pasta
`copyFile`	Duplicar um arquivo
`renameFile`	Renomear um arquivo
`deleteFile`	Mover para a lixeira ou excluir permanentemente
`listDriveFiles`	Listar qualquer tipo de arquivo no Drive com filtros
`searchDriveFiles`	Pesquisar todos os arquivos do Drive por nome ou conteúdo
`downloadFile`	Baixar o conteúdo de um arquivo

Gmail

Ferramenta	Descrição
`listMessages`	Listar ou pesquisar mensagens usando a sintaxe de consulta do Gmail (`is:unread`, `from:`, `newer_than:`, etc.)
`getMessage`	Buscar uma única mensagem com cabeçalhos decodificados, corpo em texto simples, corpo em HTML e metadados de anexos
`sendEmail`	Enviar um e-mail em texto simples. Suporta cc/bcc e respostas em thread via `replyToMessageId`
`trashMessage`	Mover uma mensagem para a Lixeira (reversível, igual a clicar em Excluir na interface do Gmail)
`modifyMessageLabels`	Adicionar ou remover rótulos em uma mensagem — use para favoritar, arquivar (remover `INBOX`), marcar como lida (remover `UNREAD`)
`listLabels`	Listar todos os rótulos do sistema e personalizados com seus IDs
`createDraft`	Criar um rascunho em vez de enviar imediatamente — para fluxos de criar/revisar/enviar
`listDrafts`	Listar rascunhos existentes com destinatário, assunto e resumo
`getDraft`	Buscar um único rascunho com cabeçalhos e corpo completos
`updateDraft`	Substituir o conteúdo de um rascunho existente (substituição completa, não um patch)
`sendDraft`	Enviar um rascunho existente pelo ID
`deleteDraft`	Excluir permanentemente um rascunho (não vai para a Lixeira — é removido)
`triageInbox`	Composto: buscar mensagens não lidas com conteúdo + sinalizadores heurísticos (newsletter, reunião, ação) para triagem de caixa de entrada em uma única etapa

Google Calendar

Ferramenta	Descrição
`listEvents`	Listar ou pesquisar eventos com `q`, `timeMin`, `timeMax`, `maxResults` (o padrão é o calendário principal)
`createEvent`	Criar um evento com título, início/fim, descrição, local, participantes, link opcional do Google Meet
`updateEvent`	Atualização estilo PATCH — apenas os campos que você enviar são alterados. Use para remarcar, renomear, alterar participantes
`deleteEvent`	Excluir permanentemente um evento. O `sendUpdates` opcional envia cancelamentos por e-mail aos participantes
`quickAddEvent`	Criação de eventos em linguagem natural: `"Lunch with Sarah tomorrow 12pm"` — o Google interpreta o restante

Apps Script

Automatize a automação: crie e edite o Apps Script por trás de um Documento ou Planilha — onEdit gatilhos, menus personalizados, tarefas agendadas — em vez de pedir ao usuário para colar código no editor manualmente.

Ferramenta	Descrição
`createAppsScriptProject`	Criar um projeto, opcionalmente vinculado a um Documento/Planilha/Apresentação/Formulário via `parentId`, e gravar seus arquivos iniciais na mesma chamada
`getAppsScriptContent`	Ler os arquivos de um projeto — passe `includeSource: false` para uma listagem rápida, ou `versionNumber` para ler uma versão salva
`updateAppsScriptContent`	Gravar arquivos. `merge` (padrão) substitui arquivos com o mesmo nome e mantém os demais; `replace` faz o projeto ficar exatamente com os arquivos que você enviar

Exige duas coisas além da configuração usual:

A API Apps Script deve estar ativada por conta Google em https://script.google.com/home/usersettings — ela fica desativada por padrão, e um erro 403 com "Apps Script API" na mensagem significa que esta etapa foi ignorada.
O escopo script.projects, que está incluído em SCOPES. Instalações existentes precisam autorizar novamente uma vez para ativá-lo.

Exemplos de Uso

Google Docs

"Read document ABC123 as markdown"
"Append 'Meeting notes for today' to document ABC123"
"Make the text 'Important' bold and red in document ABC123"
"Replace the entire document with this markdown: # Title\n\nNew content here"
"Insert a 3x4 table at index 50 in document ABC123"

Google Sheets

"Read range A1:D10 from spreadsheet XYZ789"
"Write [[Name, Score], [Alice, 95], [Bob, 87]] to range A1 in spreadsheet XYZ789"
"Create a new spreadsheet titled 'Q1 Report'"
"Format row 1 as bold with a light blue background in spreadsheet XYZ789"
"Freeze the first row in spreadsheet XYZ789"
"Add a dropdown with options [Open, In Progress, Done] to range C2:C100"
"Create a table named 'Tasks' in range A1:D10 with columns: Task (TEXT), Status (DROPDOWN: 'Not Started','In Progress','Done'), Priority (NUMBER)"
"Add a medium solid border around A1:D10 in spreadsheet XYZ789"
"Protect the header row so collaborators can't accidentally edit it"
"Auto-fit row heights for rows 2–50 after wrapping text"

Google Drive

"List my 10 most recent Google Docs"
"Search for documents containing 'project proposal'"
"Create a folder called 'Meeting Notes' and move document ABC123 into it"

Gmail

"Show me my 20 most recent unread emails"
"Search Gmail for messages from alice@example.com in the last 7 days"
"Read the full body of message ID 18c3f4a2b1d9"
"Send an email to bob@example.com with the subject 'Weekly update' and this body..."
"Reply to message 18c3f4a2b1d9 with 'Thanks, confirmed.'"
"Star message 18c3f4a2b1d9 and archive it"
"Move message 18c3f4a2b1d9 to Trash"
"List all my Gmail labels"
"Draft a reply to that email but don't send it yet — let me review first"
"Show me my drafts, then send the one to bob@"
"Triage my unread inbox: tell me which 20 emails need attention and which are noise"

Google Calendar

"What's on my calendar this week?"
"Create an event titled 'Project review' tomorrow from 2pm to 3pm Pacific time"
"Quick add: lunch with Alex Friday 12:30"
"Reschedule event abc123 to next Monday at 10am"
"Delete the 'Standup' event tomorrow"
"List all events on my calendar between April 15 and April 22"
"Schedule a 30-minute meeting with bob@example.com next Wednesday at 11am with a Google Meet link"

Fluxo de Trabalho com Markdown

O servidor suporta um fluxo de trabalho completo de ida e volta com markdown:

Ler um documento como markdown: readDocument com format='markdown'
Editar o markdown localmente
Enviar as alterações de volta: replaceDocumentWithMarkdown

Suportados: títulos, negrito, itálico, tachado, links, listas com marcadores/numeradas, linhas horizontais.

Verificação ao Vivo de Documentos

O repositório inclui um teste de integração ao vivo opcional para cloneTable contra a API real do Google Docs. Ele é ignorado por padrão.

Requisitos:

GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET válidos
um token autorizado já armazenado via npx -y @a-bonus/google-docs-mcp auth

Execute com:

GOOGLE_DOCS_LIVE_TESTS=1 npm run test:live:docs

Este teste cria Documentos Google de origem/destino temporários, verifica cloneTable e depois exclui os arquivos de teste.

Implantação Remota

Implante o servidor centralmente no Google Cloud Run (ou em qualquer host de contêiner) para que sua equipe possa usá-lo sem instalações locais. O servidor usa MCP OAuth 2.1 com o GoogleProvider integrado do FastMCP — os clientes MCP lidam com o fluxo de autenticação automaticamente.

Visite a URL raiz do servidor (/) para instruções de configuração e uma configuração de cliente pronta para copiar.

Variáveis de Ambiente

Variável	Descrição
`MCP_TRANSPORT`	Defina como `httpStream` para ativar o modo remoto (padrão: `stdio`)
`BASE_URL`	URL pública do servidor implantado (necessária para redirecionamentos OAuth)
`GOOGLE_CLIENT_ID`	ID do cliente OAuth (tipo Aplicativo Web)
`GOOGLE_CLIENT_SECRET`	Segredo do cliente OAuth
`MCP_TOOL_GROUPS`	Grupos de ferramentas opcionais separados por vírgula para registrar: `docs`, `drive`, `sheets`, `utils`, `gmail`, `calendar`, `script` ou `all`
`ALLOWED_DOMAINS`	Lista separada por vírgulas de domínios permitidos do Google Workspace (opcional)
`PORT`	Porta HTTP (padrão: `8080`)
`TOKEN_STORE`	Defina como `firestore` para armazenamento persistente de tokens (padrão: em memória)
`JWT_SIGNING_KEY`	Chave de assinatura fixa para que os tokens sobrevivam a reinicializações (gerada automaticamente se não definida)
`REFRESH_TOKEN_TTL`	Tempo de vida do token de atualização em segundos (padrão: `2592000` / 30 dias)
`GCLOUD_PROJECT`	ID do projeto GCP para Firestore (necessário quando `TOKEN_STORE=firestore`)
`MCP_STATELESS`	Defina como `true` para implantações sem servidor (Cloud Run, etc.) — desativa o rastreamento de sessão para sobreviver ao scale-to-zero

Configuração

Crie um projeto GCP e ative as APIs Docs, Sheets e Drive
Crie um cliente OAuth (tipo Aplicativo Web, não Desktop)
Defina o URI de redirecionamento autorizado como {BASE_URL}/oauth/callback
Implante no Cloud Run:

gcloud run deploy google-docs-mcp \
  --source . \
  --region europe-west3 \
  --port 8080 \
  --allow-unauthenticated \
  --set-env-vars "^|^MCP_TRANSPORT=httpStream|BASE_URL=https://your-service.run.app|ALLOWED_DOMAINS=yourdomain.com|GOOGLE_CLIENT_ID=...|GOOGLE_CLIENT_SECRET=...|TOKEN_STORE=firestore|JWT_SIGNING_KEY=your-secret-key"

Observação: O prefixo ^|^ altera o delimitador da variável de ambiente de , para | porque ALLOWED_DOMAINS contém vírgulas.

Como Funciona

Por padrão, as sessões OAuth são armazenadas em memória e perdidas ao reiniciar
Para produção, defina TOKEN_STORE=firestore e JWT_SIGNING_KEY para autenticação persistente entre implantações e inicializações a frio
Em plataformas sem servidor (Cloud Run, etc.), defina MCP_STATELESS=true — as sessões MCP ficam em memória, então o scale-to-zero as apaga. O modo sem estado desativa completamente o rastreamento de sessão; cada solicitação autentica de forma independente via fluxo de token JWT/Firestore
ALLOWED_DOMAINS restringe o acesso a domínios específicos do Google Workspace
Os tokens de acesso são atualizados automaticamente; sessões inativas expiram após 30 dias
Os usuários podem revogar o acesso a qualquer momento via Permissões da conta Google

Atualizando Sua Implantação

Mesclar alterações em main não atualiza automaticamente seu serviço no Cloud Run. Cada implantação é independente — você precisa reimplantar manualmente quando quiser novos recursos ou correções.

Para atualizar:

Baixe o código mais recente:
```
git pull origin main
```
Reimplante no Cloud Run:
```
gcloud run deploy your-service-name --source . --region your-region
```
Suas variáveis de ambiente existentes são preservadas — não é necessário passar --set-env-vars novamente.

Quando reimplantar:

Correções de bugs e patches de segurança — reimplante o mais rápido possível
Novos recursos — reimplante quando for conveniente
Alterações que quebram compatibilidade — verifique as notas de versão antes de reimplantar

Você pode verificar sua versão atual em relação ao lançamento mais recente na página de versões.

Opções de Autenticação

OAuth (Padrão)

Passe as credenciais do cliente OAuth do Google Cloud como variáveis de ambiente:

Variável	Descrição
`GOOGLE_CLIENT_ID`	ID do cliente OAuth do Google Cloud Console
`GOOGLE_CLIENT_SECRET`	Segredo do cliente OAuth do Google Cloud Console

Conta de Serviço (Empresarial)

Para Google Workspace com delegação em todo o domínio:

Variável	Descrição
`SERVICE_ACCOUNT_PATH`	Caminho para o arquivo JSON da chave da conta de serviço
`GOOGLE_IMPERSONATE_USER`	E-mail do usuário a personificar (opcional)

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "SERVICE_ACCOUNT_PATH": "/path/to/service-account-key.json",
        "GOOGLE_IMPERSONATE_USER": "user@yourdomain.com"
      }
    }
  }
}

Armazenamento de Tokens

Os tokens de atualização OAuth são armazenados em ~/.config/google-docs-mcp/token.json (respeita XDG_CONFIG_HOME). IDs de cliente OAuth e segredos de cliente não são armazenados no arquivo de token. Para reautorizar, execute o comando auth novamente ou exclua o arquivo de token.

Várias Contas Google

Defina GOOGLE_MCP_PROFILE para armazenar tokens em um subdiretório específico do perfil. Isso permite usar diferentes contas Google para diferentes projetos:

Variável	Descrição
`GOOGLE_MCP_PROFILE`	Nome do perfil para armazenamento isolado de tokens (opcional)

{
  "mcpServers": {
    "google-docs": {
      "command": "npx",
      "args": ["-y", "@a-bonus/google-docs-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "...",
        "GOOGLE_CLIENT_SECRET": "...",
        "GOOGLE_MCP_PROFILE": "work"
      }
    }
  }
}

Os tokens são armazenados por perfil:

~/.config/google-docs-mcp/
├── token.json              # default (no profile)
├── work/token.json         # GOOGLE_MCP_PROFILE=work
├── personal/token.json     # GOOGLE_MCP_PROFILE=personal

Sem GOOGLE_MCP_PROFILE, o comportamento permanece inalterado.

Limitações Conhecidas

Ancoragem de comentários: Comentários criados programaticamente aparecem na lista de comentários, mas não ficam visivelmente ancorados ao texto na interface do Google Docs. Isso é uma limitação da API do Google Drive.
Ancoragem de comentários em planilhas: Comentários criados via API em planilhas podem armazenar metadados de âncora, mas os editores do Google Workspace tratam âncoras da API do Drive como comentários não ancorados. Use createSheetsComment com includeCellLink=true para um link clicável para a célula de destino, ou createSheetsCellNote quando o texto da revisão precisar estar anexado à própria célula.
Resolução de comentários: O status de resolvido pode não persistir na interface do Google Docs.
Documentos convertidos: Documentos convertidos do Word podem não suportar todas as operações da API.
Imagens Markdown: Ainda não suportadas na conversão de Markdown para Docs.
Listas profundamente aninhadas: Listas com 3 ou mais níveis de aninhamento podem apresentar peculiaridades de formatação.
Exclusão definitiva do Gmail: trashMessage move mensagens para a Lixeira (reversível). A exclusão permanente requer o escopo mais amplo https://mail.google.com/ e não está exposta na v0.1.
Anexos do Gmail: getMessage retorna metadados de anexos, mas ainda não baixa os bytes dos anexos.
Envio de e-mail HTML no Gmail: sendEmail envia apenas texto simples. Para corpos HTML, cole o HTML no campo body — ele será entregue como texto, não renderizado.
Escopo do Calendar: calendar.events permite operações CRUD de eventos em calendários existentes, mas não pode criar ou excluir calendários inteiros.
Apps Script API desativada por padrão: toda conta precisa habilitá-la uma vez em https://script.google.com/home/usersettings. As ferramentas não podem ativá-la por você.
Implantação do Apps Script: as ferramentas editam o código-fonte do projeto. Criar versões, implantações e gatilhos instaláveis ainda não é exposto — gatilhos simples como onEdit e onOpen funcionam sem nada disso.
Eventos recorrentes do Calendar: updateEvent e deleteEvent modificam toda a série recorrente, a menos que você direcione um ID de instância específico retornado por listEvents com singleEvents=true.

Solução de problemas

O servidor não inicia:
- Verifique se GOOGLE_CLIENT_ID e GOOGLE_CLIENT_SECRET estão definidos no bloco env da sua configuração MCP.
- Tente executar manualmente: npx @a-bonus/google-docs-mcp e verifique o stderr para erros.
Erros de autorização:
- Garanta que as APIs Docs, Sheets, Drive, Gmail e Calendar estejam habilitadas no Google Cloud Console.
- Confirme que seu e-mail está listado como Usuário de Teste na tela de consentimento OAuth e que todos os escopos necessários (Docs, Sheets, Drive, gmail.modify, calendar.events) foram adicionados à tela de consentimento.
- Reautorize: npx @a-bonus/google-docs-mcp auth
- Exclua ~/.config/google-docs-mcp/token.json e reautorize ao atualizar — os escopos do Gmail e Calendar foram adicionados em versões posteriores, então os tokens existentes precisam ser atualizados.
- Usuários remotos (Cloud Run) devem sair e entrar novamente no cliente MCP para que o Google reemita o consentimento com a nova lista de escopos.
Erros de abas:
- Use listTabs para ver os IDs de abas disponíveis.
- Omita tabId para documentos de aba única.
"Página não encontrada" no claude.ai durante o login OAuth (implantações remotas):
- Sintoma: clicar em Conectar em um conector MCP personalizado leva à página "Página não encontrada" do Claude em vez da tela de login do Google.
- Causa: inicialização a frio do Cloud Run. A primeira solicitação a um serviço ocioso expira antes que o contêiner termine de iniciar, e o Claude roteia o redirecionamento falho para sua página 404.
- Solução alternativa: atualize a página com força (Cmd+Shift+R no macOS, Ctrl+Shift+R no Windows/Linux). A segunda solicitação atinge uma instância já ativa e o fluxo OAuth prossegue normalmente.
- Correção permanente: defina --min-instances=1 no seu serviço Cloud Run para manter uma instância sempre ativa (gcloud run services update <service> --region <region> --min-instances=1). Custa cerca de US$ 2–3/mês pela reserva de memória.
Reautenticação inesperada após uma reimplantação (implantações remotas):
- Causa: JWT_SIGNING_KEY é gerado automaticamente a cada inicialização do contêiner, então reimplantações invalidam todas as sessões emitidas anteriormente.
- Correção: defina uma variável de ambiente JWT_SIGNING_KEY estável no serviço Cloud Run para que ela sobreviva a reinicializações: gcloud run services update <service> --region <region> --update-env-vars JWT_SIGNING_KEY=$(openssl rand -hex 32). Sessões emitidas após essa alteração sobreviverão a futuras reimplantações.
Alto uso de CPU com múltiplas sessões MCP: Alguns clientes chamam tools/list com muita frequência. Caso contrário, o FastMCP recalcula o JSON Schema para cada ferramenta em cada solicitação, o que pode fixar um núcleo de CPU por processo. Este servidor pré-computa o payload uma vez antes do início do stdio e substitui o manipulador tools/list por um snapshot em cache. Se você ainda observar carga sustentada, capture alguns segundos com sample <pid> 1 10 (macOS) ou node --cpu-prof e relate.

Detalhes da Configuração do Google Cloud

Instruções passo a passo do Google Cloud Console

Para implantação remota, crie um cliente OAuth do tipo Aplicativo web (não Aplicativo de desktop). Use Aplicativo de desktop apenas para uso local via stdio.

Acesse o Google Cloud Console: Abra console.cloud.google.com
Crie ou Selecione um Projeto: Clique no menu suspenso do projeto > "NOVO PROJETO". Dê um nome (ex.: "MCP Docs Server") e clique em "CRIAR".
Habilite as APIs:
- Navegue até "APIs e serviços" > "Biblioteca"
- Pesquise e habilite: Google Docs API, Google Sheets API, Google Drive API, Gmail API, Google Calendar API
Configure a Tela de Consentimento OAuth:
- Vá para "APIs e serviços" > "Tela de consentimento OAuth"
- Escolha "Externo" e clique em "CRIAR"
- Preencha: Nome do aplicativo, E-mail de suporte ao usuário, E-mail de contato do desenvolvedor
- Clique em "SALVAR E CONTINUAR"
- Adicione escopos: documents, spreadsheets, drive, gmail.modify, calendar.events
- Clique em "SALVAR E CONTINUAR"
- Adicione seu e-mail do Google como Usuário de Teste
- Clique em "SALVAR E CONTINUAR"
Crie Credenciais:
- Vá para "APIs e serviços" > "Credenciais"
- Clique em "+ CRIAR CREDENCIAIS" > "ID do cliente OAuth"
- Tipo de aplicativo: "Aplicativo de desktop"
- Clique em "CRIAR"
- Copie o ID do cliente e o Segredo do cliente

Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para configuração de desenvolvimento, visão geral da arquitetura e diretrizes.

Licença

MIT — veja LICENSE para detalhes.