Google Workspace

Gerencie Gmail, Calendário, Drive e Contatos através das APIs do Google Workspace usando OAuth 2.0.

Documentação

Google Workspace MCP Server

Dê ao seu agente de IA acesso real ao Google Workspace — Gmail, Calendar, Drive, Docs, Sheets, Tasks, Meet e Contacts — a partir de um único servidor MCP, em quantas contas você tiver.

Pesquise seus e-mails, consulte sua agenda, escreva um documento, registre uma tarefa — em conversa, como você mesmo.

Instalação

Primeiro, você precisa de credenciais OAuth do Google — o único pré-requisito comum a todos os caminhos:

Acesse console.cloud.google.com/apis/credentials
Crie um ID de cliente OAuth 2.0, tipo de aplicativo Aplicativo de desktop
Ative as APIs que você deseja (Gmail, Calendar, Drive, Sheets, Docs, Tasks, Meet — e a People API para contatos, que é como o Google a chama no console)
Mantenha o ID do cliente e o Segredo do cliente à mão — você os colará abaixo

Depois, escolha o caminho que corresponde à sua forma de trabalhar. Todos os três executam o mesmo servidor.

Node 22.12 ou mais recente. (Node 18 e 20 estão ambos em fim de vida.)

📦 → 🤖 Claude Desktop — instalação com um clique via `.mcpb` (recomendado)

Baixe o google-workspace-mcp.mcpb da última versão e arraste-o para a janela do Claude Desktop ou clique duas vezes nele.

O Claude Desktop abre uma caixa de diálogo de instalação com três campos:

Campo
Google OAuth Client ID	obrigatório — da etapa acima
Google OAuth Client Secret	obrigatório — da etapa acima
Workspace Directory	opcional — onde anexos, downloads e exportações são salvos. O padrão é `~/.local/share/google-workspace-mcp/workspace/`. Dê a ele uma pasta dedicada — não sua pasta pessoal, Documentos, Área de Trabalho ou uma pasta do Google Drive.

Cole, salve, pronto. Sem JSON para editar, sem Node para instalar, sem caminhos para acertar — o pacote carrega o servidor e todas as dependências.

Um único pacote cobre todas as plataformas — macOS (Intel e Apple Silicon), Linux (x64 e ARM64) e Windows. Não há nada para escolher: o servidor é JavaScript puro, então não há carga específica de plataforma para selecionar.

Nota multiplataforma: arquivos .mcpb são instalados pelo manipulador integrado do Claude Desktop. Se o clique duplo não acionar o Claude no seu sistema, arraste o arquivo para a janela do Claude Desktop ou clique com o botão direito → "Abrir com…" e escolha Claude Desktop (depois "sempre abrir com" se o seu sistema operacional oferecer). O comportamento varia: macOS geralmente associa automaticamente, Windows pode exigir uma associação única, Linux varia conforme o ambiente de desktop.

Claude Code — um comando

claude mcp add google-workspace \
  -e GOOGLE_CLIENT_ID=your-client-id \
  -e GOOGLE_CLIENT_SECRET=your-client-secret \
  -- npx -y @aaronsb/google-workspace-mcp

É isso — nenhum arquivo para editar. Verifique com /mcp.

Outros clientes MCP

Adicione uma entrada ao arquivo de configuração MCP do cliente (para Claude Desktop manualmente, é claude_desktop_config.json; para Claude Code, .mcp.json):

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

Ou instale globalmente e aponte diretamente para o binário:

npm install -g @aaronsb/google-workspace-mcp

Como tudo se encaixa

flowchart LR
    human["🧑 You<br>ask in plain language"]
    agent["🤖 Your AI agent<br>Claude Desktop, Claude Code…"]
    server["⚙️ This MCP server<br>picks the right account,<br>builds the real request"]
    keys[("🔑 Your accounts<br>OAuth tokens, kept<br>on your own machine")]
    google["☁️ Google<br>Gmail · Calendar · Drive · Docs<br>Sheets · Tasks · Meet · Contacts"]

    human -->|"“what's on my calendar?”"| agent
    agent -->|"tool call"| server
    server <-->|"which account?"| keys
    server -->|"real API call, as you"| google
    google -->|"your data"| server
    server -->|"shaped for an agent<br>+ what to do next"| agent
    agent -->|"an answer"| human

    classDef person   fill:#475569,color:#ffffff,stroke:#94a3b8
    classDef robot    fill:#2d7d9a,color:#ffffff,stroke:#4a5568
    classDef ours     fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
    classDef secrets  fill:#2d8e5e,color:#ffffff,stroke:#4a5568
    classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706

    class human person
    class agent robot
    class server ours
    class keys secrets
    class google external

Suas credenciais nunca saem da sua máquina. O servidor mantém um token OAuth por conta, no seu próprio disco, e chama o Google como você — não há serviço intermediário, nenhuma conta nossa, nada para se cadastrar. Adicione quantas contas quiser (pessoais e de trabalho, lado a lado); o servidor roteia cada solicitação para a conta certa.

O que ele pode fazer

12 ferramentas em 8 serviços do Google, além de gerenciamento de múltiplas contas, acesso somente leitura por conta, execução em lote, criação de conteúdo e uma área de trabalho isolada para arquivos.

Ferramenta	O que faz
`manage_email`	Gmail — pesquisar, ler (HTML simples ou sanitizado), enviar, responder / responder a todos, encaminhar, triar, excluir, rótulos, conversas, anexos
`manage_calendar`	Calendar — listar, agenda, obter, criar, quickAdd (linguagem natural), atualizar, excluir, calendários, freebusy
`manage_drive`	Drive — pesquisar, obter, enviar, baixar, copiar, renomear / mover, excluir, exportar, permissões, comentários, visualizar imagens
`manage_sheets`	Sheets — ler / escrever intervalos (saída com numeração de linhas), anexar, limpar, gerenciar abas, copiar / duplicar / renomear
`manage_docs`	Docs — obter, criar, anexar, inserir texto, localizar e substituir
`manage_tasks`	Tasks — listar / criar / atualizar / concluir tarefas e listas de tarefas
`manage_meet`	Meet — criar e configurar espaços de reunião, ver quem está em uma chamada agora, navegar por conferências passadas, participantes, transcrições, gravações, notas inteligentes
`manage_contacts`	Contacts — procurar pessoas nos seus contatos salvos, nos endereços com os quais você apenas se correspondeu e no diretório da sua organização; criar, atualizar e excluir contatos
`manage_accounts`	Ciclo de vida de múltiplas contas — adicionar contas, gerenciar credenciais e escopos
`manage_scratchpad`	Compor / editar conteúdo de várias linhas (endereçado por linha ou caminho JSON), anexar arquivos, enviar para qualquer destino; o modo JSON sincroniza ao vivo com Docs / Sheets
`manage_workspace`	Operações de arquivo na área de trabalho isolada (ponto de troca para anexos, downloads, exportações)
`bulk_operations`	Fazer muitas coisas em uma única chamada — encadear diferentes operações em sequência com referências `$N.field`, ou aplicar uma operação a muitos recursos em uma única solicitação do Google (`queue_operations` ainda funciona como alias)

Cada resposta traz orientação de próximos passos, para que o agente sempre saiba o que pode fazer em seguida.

Um pedido, muitos passos

A parte útil não é nenhuma operação isolada — é que seu agente pode encadeá-las.

Você pede uma coisa. O agente descobre que precisa de quatro chamadas de API, em ordem, cada uma alimentando a próxima:

sequenceDiagram
    autonumber
    participant H as 🧑 You
    participant A as 🤖 Your agent
    participant S as ⚙️ MCP server
    participant G as ☁️ Google

    H->>A: "file the invoice from Acme<br>and remind me to pay it Friday"
    A->>S: find the email
    S->>G: search Gmail
    G-->>S: the message
    S-->>A: found it — and here's what you can do next
    A->>S: save the attachment
    S->>G: download it
    A->>S: put it in Drive
    S->>G: upload
    A->>S: create a task, due Friday
    S->>G: Google Tasks
    A-->>H: Done. Invoice filed, task set for Friday.

Duas coisas fazem isso funcionar. Cada resposta diz ao agente o que ele pode fazer em seguida, para que ele não fique adivinhando o próximo passo. E o bulk_operations permite executar uma cadeia inteira em uma única chamada, alimentando cada resultado no próximo — então "encontre a fatura, arquive-a, lembre-me" é uma única ida e volta em vez de quatro.

Quando o trabalho é a mesma operação sobre muitas coisas, ele pode ir além e usar uma única solicitação do Google para todas:

bulk_operations { mode: 'batch', tool: 'manage_email', operation: 'trash',
                  items: ['msg1', 'msg2', 'msg3', … ] }

Duzentas mensagens excluídas em uma única ida e volta em vez de duzentas. Isso é propositalmente restrito — funciona apenas onde o Google publica um método para isso, que hoje é contatos (criar, atualizar, excluir, obter) e Gmail (excluir, alterações de rótulo). Peça em qualquer outro lugar e a resposta nomeia as operações que podem, e aponta você de volta para o modo sequencial, que funciona em todos os lugares.

Peça o que está faltando

Este servidor expõe 95 operações, alcançando 79 dos 257 métodos que o Google publica nessas oito APIs. É um subconjunto curado de propósito: um agente tem que escolher entre eles, e cada método que ele precisa pesar é um que ele pode escolher errado. Uma ferramenta com 257 operações não é mais capaz do que uma com 95 — é mais difícil de usar corretamente.

Mas esse julgamento foi feito sem você.

→ Navegue por todos os métodos que o Google publica

Cada método está listado — o que faz, se o expomos, e um link Request que abre uma issue pré-preenchida. As descrições são as do próprio Google, citadas textualmente, e a página é gerada a partir da mesma especificação da qual o cliente é construído, então não pode divergir da realidade.

Essa página também lista três APIs inteiras que este servidor ainda não toca — Chat, Slides e Forms — pela mesma razão: não direcionado é uma decisão, não um fato da natureza.

Um bom pedido nomeia a tarefa, não o método:

"Quero que o agente arquive faturas recebidas automaticamente em uma pasta."

Isso pode ser avaliado. Pode ser que uma operação existente já faça isso, ou que a resposta certa seja um método diferente do que você encontrou. "Expor users.settings.filters.create" é uma conclusão, não um caso — comece pelo problema e deixe o método seguir.

Por que Apache 2.0, e não open core

Tudo está aqui. Não há nível pago, nenhuma versão "enterprise", nenhum recurso retido para vender depois. O que você instala é o que existe.

Open core funciona guardando a parte boa. A coisa gratuita é um ímã de leads, e no momento em que seu uso fica sério, você descobre que a operação que precisa está atrás de uma licença. Esse modelo seria especialmente ruim aqui: esta é uma peça de encanamento entre você e seus próprios dados, usando suas próprias credenciais do Google, rodando na sua própria máquina. Nada nesse arranjo deveria ter um paywall no meio, e nada nele precisa de um fornecedor.

Apache 2.0 em vez de MIT por duas razões concretas:

Uma concessão explícita de patentes. Os contribuidores licenciam suas reivindicações de patente junto com seu código, então usar isso não pode se tornar um problema de patente mais tarde. O MIT é silencioso sobre patentes, o que significa que a questão é apenas não respondida, não resolvida.
É seguro adotar no trabalho. Apache 2.0 está essencialmente em toda lista de permissões corporativa. Faça um fork, incorpore, envie dentro de um produto comercial — você não deve nada a ninguém e não precisa pedir.

A única obrigação é a atribuição: mantenha os avisos (NOTICE, LICENSE) com o código. Só isso.

Até a v3.0.0, este projeto era licenciado sob MIT, e essa história é preservada em vez de apagada — contribuições da era MIT mantêm seu aviso original em LICENSE-MIT, e seus autores são creditados em NOTICE. Apache 2.0 não retira nada que o MIT permitia.

Uso

Adicione uma conta (abre um navegador para OAuth):

manage_accounts { "operation": "authenticate" }

Depois use qualquer ferramenta com o e-mail da sua conta:

manage_email    { "operation": "triage", "email": "you@gmail.com" }
manage_calendar { "operation": "agenda", "email": "you@gmail.com" }
manage_drive    { "operation": "search", "email": "you@gmail.com", "query": "quarterly report" }

Dar a uma conta acesso somente leitura

Algumas contas nunca devem ser gravadas. Peça menos no momento do consentimento e o próprio token não pode enviar, editar ou excluir — isso não é uma regra sobreposta a um token amplo:

manage_accounts { "operation": "scopes", "email": "you@gmail.com",
                  "services": "gmail,drive,contacts", "access": "read" }

O Google recebe a variante somente leitura de cada escopo, então marcar todas as caixas na tela de consentimento ainda gera um token somente leitura. manage_accounts status informa o que cada conta realmente possui.

Uma gravação de uma conta somente leitura é recusada antes que a solicitação saia, com a conta, a operação e o caminho de volta:

'create' needs write access to contacts. Account you@gmail.com was authorized
read-only for contacts. Re-authorize with manage_accounts {operation:'scopes',
email:'you@gmail.com', services:'contacts', access:'readwrite'}, or use an
account that already has it.

Onde um serviço não tem escopo somente leitura, você é informado quais são e o que eles ainda poderão fazer antes de o navegador abrir.

Fluxos de trabalho de várias etapas

Encadeie operações com referências de resultado — a saída de uma etapa alimenta a próxima:

{
  "operations": [
    { "tool": "manage_email", "args": { "operation": "search", "email": "you@gmail.com", "query": "from:boss subject:review" }},
    { "tool": "manage_email", "args": { "operation": "read", "email": "you@gmail.com", "messageId": "$0.messageId" }}
  ]
}

Uma operação, muitas coisas

Onde o Google publica um método para isso, a mesma operação em muitos recursos custa uma solicitação:

{
  "mode": "batch",
  "tool": "manage_contacts",
  "operation": "delete",
  "email": "you@gmail.com",
  "items": ["people/c1", "people/c2", "people/c3"]
}

Qualquer coisa compartilhada por todo o lote vai no nível superior; items carregam apenas o que difere — um id simples é suficiente quando é só isso.

Onde seus dados vivem

Segue a Especificação de Diretório Base XDG:

Dados	Localização
Registro de contas	`~/.config/google-workspace-mcp/accounts.json`
Credenciais	`~/.local/share/google-workspace-mcp/credentials/`
Workspace (troca de arquivos)	`~/.local/share/google-workspace-mcp/workspace/`

As credenciais são arquivos por conta que contêm tokens OAuth padrão. Nenhum segredo é armazenado no diretório do projeto.

Por baixo dos panos

Você não precisa de nada disso para usar o servidor. Mas se estiver curioso, ou quiser adicionar uma operação:

O servidor constrói seu cliente de API do Google a partir das especificações de API legíveis por máquina do próprio Google. Nada é transcrito manualmente, então a superfície não pode divergir da realidade, e adicionar uma operação é uma edição de YAML em vez de uma mudança de código.

Como funciona — a divisão tempo de compilação / tempo de execução, o descritor, a fábrica
Cobertura da API — o que está exposto, o que não está e como pedir mais
A superfície completa da API — todos os métodos que o Google publica, além das três APIs que ainda não direcionamos
Decisões de arquitetura — os ADRs, incluindo por que este servidor possui seu cliente do Google diretamente

Licença

Apache License 2.0 — veja Por que Apache 2.0 acima.

Google Workspace

Documentação