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 e Meet — 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 das 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 App para desktop
Ative as APIs desejadas (Gmail, Calendar, Drive, Sheets, Docs, Tasks, Meet)
Mantenha o ID do cliente e o Segredo do cliente à mão — você os colará abaixo

Depois, escolha o caminho que combina com a 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 um diálogo de instalação com três campos:

Campo
ID do cliente OAuth do Google	obrigatório — do passo acima
Segredo do cliente OAuth do Google	obrigatório — do passo acima
Diretório de trabalho	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 a 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 SO oferecer). O comportamento varia: macOS geralmente associa automaticamente, Windows pode precisar de 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 para o binário diretamente:

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<br>Docs · Sheets · Tasks · Meet"]

    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

11 ferramentas em 7 serviços do Google, além de gerenciamento de múltiplas contas, processamento em lote, criação de conteúdo e um sandbox de 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 numerada por linha), 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 — navegar por conferências passadas, participantes, transcrições, gravações, notas inteligentes
`manage_accounts`	Ciclo de vida de múltiplas contas — adicionar contas, gerenciar credenciais e escopos
`manage_scratchpad`	Compor / editar conteúdo multilinha (endereçado por linha ou caminho JSON), anexar arquivos, enviar para qualquer destino; modo JSON sincroniza ao vivo com Docs / Sheets
`manage_workspace`	Operações de arquivo no sandbox do espaço de trabalho (ponto de troca para anexos, downloads, exportações)
`queue_operations`	Encadear operações sequencialmente com referências de resultado `$N.field`

Cada resposta traz orientações 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 a seguir, para que ele não fique adivinhando o próximo passo. E o queue_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.

Peça o que está faltando

Este servidor expõe 80 operações, alcançando 60 dos 233 métodos que o Google publica nessas sete APIs. É um subconjunto curado de propósito: um agente precisa escolher entre eles, e cada método que ele precisa pesar é um que ele pode escolher errado. Uma ferramenta com 233 operações não é mais capaz do que uma com 80 — é 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 nós o expomos, e um link Solicitar que abre uma issue pré-preenchida. As descrições são as do próprio Google, citadas na íntegra, 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 quatro APIs inteiras que este servidor ainda não toca — Chat, Contacts, Slides e Forms — pela mesma razão: não ter como alvo é 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 automaticamente as faturas recebidas 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, em vez de 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 permissão.

A única obrigação é a atribuição: mantenha os avisos (NOTICE, LICENSE) junto 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. O Apache 2.0 não tira 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" }

Fluxos de Trabalho com Múltiplas 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" }}
  ]
}

Onde seus dados ficam

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/`
Espaço de trabalho (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, não uma mudança de código.

Como funciona — a divisão entre tempo de build / 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 quatro APIs que ainda não temos como alvo
Decisões de arquitetura — os ADRs, incluindo por que este servidor é dono do seu cliente Google por completo

Licença

Apache License 2.0 — veja Por que Apache 2.0 acima.

Google Workspace

Documentação