Google Workspace MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

12 serviços em um servidor: Gmail, Drive, Calendar, Docs, Sheets, Slides, Forms, Tasks, Contacts, Chat, Apps Script, Custom Search
Conjunto de tools em níveis (core / extended / complete) mantém a lista gerenciável
OAuth 2.0 + 2.1 com modo bearer-token multi-usuário para implantações hospedadas
Modo stateless para Docker / Kubernetes
Cache de tokens criptografado localmente; armazenamento opcional de credenciais no GCS

Demo ao vivo

Como fica na prática

google-workspace-mcp.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "google-workspace-mcp": {
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "google-workspace-mcp",
      "command": "uvx",
      "args": [
        "workspace-mcp",
        "--tool-tier",
        "core"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "google-workspace-mcp": {
      "command": {
        "path": "uvx",
        "args": [
          "workspace-mcp",
          "--tool-tier",
          "core"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add google-workspace-mcp -- uvx workspace-mcp --tool-tier core

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Google Workspace MCP

Triagem do inbox do Gmail até o zero com Claude como assistente

👤 Qualquer pessoa com 200+ e-mails não lidos ⏱ ~25 min beginner

Quando usar: Segunda de manhã e sua caixa de entrada é uma muralha.

Pré-requisitos

Client OAuth do Google Cloud — Crie credenciais OAuth 2.0 em console.cloud.google.com e baixe o client_secret.json
Servidor instalado — uvx workspace-mcp --tool-tier core (na primeira chamada abre o navegador para OAuth)

Fluxo

Classificar o inbox

Use google-workspace-mcp. Liste os e-mails não lidos dos últimos 7 dias. Classifique em: requer-ação, informativo, newsletters, automatizados.✓ Copiado

→ Contagem por categoria com amostras de assunto
Arquivar categorias de baixo valor

Archive everything in newsletters + automated. Don't touch action-required.✓ Copiado

→ N arquivados, 0 de requer-ação afetados
Redigir respostas

For each action-required email, draft a 2-line reply in my voice. Save as drafts, don't send.✓ Copiado

→ Rascunhos visíveis no Gmail; você ajusta e envia

Resultado: Inbox abaixo de 20, respostas redigidas mas não enviadas — revisão humana completa ainda em suas mãos.

Armadilhas

Concedeu escopo completo do Gmail e se arrependeu — Use --tool-tier core — a tool send_email não aparece até você ativar o nível extended

Combine com: filesystem

Gerar relatório de status semanal a partir de atividades no Calendar + Docs

👤 ICs e gerentes que escrevem atualizações semanais ⏱ ~10 min beginner

Quando usar: Sexta à tarde e você esqueceu o que fez na semana.

Fluxo

Buscar agenda

Use google-workspace-mcp. List meetings I attended Mon–Fri this week (skip declined). For each, give 1-line context.✓ Copiado

→ Lista cronológica com contexto resumido por reunião
Buscar atividade nos Docs

List Drive docs I edited or commented on this week. Group by project.✓ Copiado

→ Lista agrupada de documentos com contagens de edições/comentários
Redigir a atualização

Combine into a 6-bullet weekly update — what I shipped, what's blocked, what's next.✓ Copiado

→ Rascunho pronto para enviar no Slack/e-mail

Resultado: Uma atualização semanal que levou 3 minutos em vez de 30, baseada em artefatos reais.

Armadilhas

Agenda cheia de 1:1s recorrentes entulha o relatório — Filtre por padrão de título do evento ou número de participantes — peça ao Claude para ignorar 1:1s recorrentes por padrão

Extrair dados estruturados de Sheets bagunçados e gravar os resultados

👤 Operações, finanças, quem vive em planilhas ⏱ ~20 min intermediate

Quando usar: Você tem uma planilha com 1000 linhas de descrições em texto livre que precisam ser categorizadas.

Fluxo

Ler o intervalo

Use google-workspace-mcp. Read column B from Sheet 'Q4 expenses' — 1000 rows of vendor descriptions.✓ Copiado

→ Linhas carregadas; amostra exibida
Categorizar

Categorize each row into: SaaS, hardware, travel, services, other. Show distribution first.✓ Copiado

→ Tabela de distribuição; exemplos de verificação
Gravar de volta

Write categories into column F. Add a header. Don't touch other columns.✓ Copiado

→ Planilha atualizada; você verifica uma amostra manualmente

Resultado: Dados categorizados na planilha, trilha de auditoria no chat.

Armadilhas

Claude sobrescreve uma coluna que você precisava — Sempre especifique a coluna de destino explicitamente; verifique algumas células antes da escrita em massa

Gerar automaticamente documentos de preparação para reuniões a partir de convites do Calendar

👤 Qualquer pessoa com reuniões seguidas ⏱ ~15 min intermediate

Quando usar: Você tem 5 reuniões amanhã e zero contexto.

Fluxo

Verificar amanhã

Use google-workspace-mcp. List tomorrow's meetings with attendees and any attached docs.✓ Copiado

→ Bloco por reunião com participantes + docs vinculados
Gerar briefs

For each, create a Doc 'Prep — <meeting title>' summarizing attached docs + suggesting 3 questions to ask.✓ Copiado

→ N Docs criados na pasta /Meeting prep/

Resultado: Entre em cada reunião preparado, não improvisando.

Armadilhas

Participantes externos não podem ver seu doc de preparação, mas um título compartilhado pode vazar intenção — Use uma pasta de preparação privada; títulos como 'Prep — <tópico>' e não '<nome de negociação sensível>'

Combinações

Combine com outros MCPs para 10× de alavancagem

google-workspace-mcp + filesystem

Sincronizar Docs do Drive localmente para edição offline ou rastreamento git

Pull all docs in /weekly-updates/ from Drive into ./drive-mirror/ as markdown.✓ Copiado

google-workspace-mcp + github

Espelhar notas de lançamento entre o GitHub e um Doc

Take the latest GitHub release notes and append them to the 'Release log' Google Doc.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
search_gmail	query: str (sintaxe de busca do Gmail), max_results?	Encontrar e-mails correspondentes a critérios em linguagem natural	1 chamada à API do Gmail
send_email	to, subject, body, cc?, bcc?	Apenas no nível extended/complete — nunca envie automaticamente sem confirmação	1 chamada de API
list_calendar_events	calendar_id, time_min, time_max	Buscar eventos em um intervalo de datas	1 chamada à API do Calendar
read_sheet_range	spreadsheet_id, range (notação A1)	Ler células de uma planilha	1 chamada à API do Sheets
write_sheet_values	spreadsheet_id, range, values[][]	Atualizar intervalos da planilha com dados calculados	1 chamada de API
create_doc	title, content (markdown)	Gerar novos documentos a partir da saída do chat	1 chamada à API do Docs
search_drive	query, mime_type?	Localizar arquivos por nome/conteúdo	1 chamada à API do Drive

Custo e limites

O que custa rodar

Cota de API: Gmail: 250 unidades de cota/usuário/seg; Calendar: 500 req/100seg; Sheets: 300 req/min/usuário
Tokens por chamada: 200–4000 dependendo da chamada (corpo completo do e-mail vs metadados)
Monetário: Gratuito para contas pessoais do Google; organizações Workspace podem ter restrições de admin
Dica: Use --tool-tier core a menos que realmente precise de Forms/Slides/Apps-Script — menos tools = system prompt menor

Segurança

Permissões, segredos, alcance

Escopos mínimos: gmail.readonly calendar.readonly drive.readonly

Armazenamento de credenciais: Cache de token criptografado localmente por padrão; opcional com suporte a GCS para hospedagem

Saída de dados: Direto para googleapis.com — sem relay de terceiros

Nunca conceda: gmail.send (até entender o risco de envio automático) drive (leitura/escrita completa em tudo)

OAuth 2.0 + 2.1 suportados; prefira cliente público PKCE a menos que tenha configuração de cliente confidencial

Solução de problemas

Erros comuns e correções

Callback OAuth falha / navegador não abre

Defina OAUTH_REDIRECT_PORT para uma porta disponível e execute novamente; em servidores sem interface use o modo device-flow

Verificar: lsof -i :8080 para confirmar que a porta está livre

403 insufficient_permissions

Re-autentique com o escopo ausente; verifique se o client OAuth o permite no Google Cloud Console

Verificar: Decodifique o token em oauth2.googleapis.com/tokeninfo para ver os escopos concedidos

Admin do Workspace bloqueia o client OAuth

Peça ao admin para adicionar seu client ID à lista de apps confiáveis, ou use uma conta Google pessoal para testes

Cota excedida em operações em massa

Adicione backoff; o servidor respeita cabeçalhos Retry-After, mas loops em massa ainda podem acionar limites por segundo

Verificar: Observe HTTP 429 nos logs

Alternativas

Google Workspace MCP vs. outros

Alternativa	Quando usar	Troca
Pipedream MCP	Você quer OAuth gerenciado + integrações Google prontas sem auto-hospedagem	Custa dinheiro em escala; dados passam pelo Pipedream
Servidores MCP por serviço (gmail-mcp, drive-mcp)	Você só precisa de um serviço Google e quer superfície mínima de escopos	Múltiplos fluxos OAuth + caches de token para gerenciar

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills