Google Workspace

Veja em ação:

O Que Ele Faz

O Workspace MCP conecta assistentes de IA a todos os doze principais serviços do Google Workspace — mais de 120 ferramentas em um único servidor MCP, com autenticação multiusuário OAuth 2.1, três níveis progressivos de ferramentas, modo somente leitura, uma CLI completa e implantação de contêiner sem estado. Ele roda localmente via stdio para clientes legados e remotamente via HTTP transmitível com implementação completa da especificação MCP mais recente.

O README cobre apenas o suficiente para você começar, com documentação extensa no site:

Segurança e Conformidade

Serviços

Cada página lista todas as ferramentas com seu nível, parâmetros, escopos necessários e exemplos de prompts. A referência completa cobre todos os doze em um só lugar.

💬 Google Chat precisa de uma configuração única do aplicativo Chat e de uma conta do Workspace — consulte o FAQ de configuração do Chat.

Início Rápido

Defina as credenciais → escolha um comando de inicialização → conecte seu cliente. Passo a passo completo com capturas de tela: workspacemcp.com/quick-start

Você precisará de um cliente OAuth do Google Cloud Console em um projeto com as APIs do Google ativadas para os serviços que planeja usar. A documentação tem links de ativação em um clique para cada API, além de um único comando gcloud services enable que cobre todas elas, e o guia de início rápido percorre toda a configuração em cerca de cinco minutos.

# 1. Credentials
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."

# 2. Launch - pick a tier
uvx workspace-mcp --tool-tier core       # essential tools
uvx workspace-mcp --tool-tier extended   # core + management ops
uvx workspace-mcp --tool-tier complete   # everything

# Or cherry-pick services
uvx workspace-mcp --tools gmail drive calendar

# 1. Credentials - MCP clients connect with PKCE and no
#    secret, but Google still requires one server-side
export MCP_ENABLE_OAUTH21=true
export GOOGLE_OAUTH_CLIENT_ID="..."
export GOOGLE_OAUTH_CLIENT_SECRET="..."
#    Alternatively, point GOOGLE_CLIENT_SECRET_PATH at a client_secret.json
#    that contains the client id and secret (env vars take precedence).
export WORKSPACE_MCP_PORT=8000
export GOOGLE_OAUTH_REDIRECT_URI="http://localhost:${WORKSPACE_MCP_PORT}/oauth2callback"
export OAUTHLIB_INSECURE_TRANSPORT=1

# 2. Launch - OAuth 2.1 requires HTTP transport
uvx workspace-mcp --transport streamable-http --tool-tier core

Níveis de ferramentas mantêm as janelas de contexto enxutas: core é o conjunto essencial, extended adiciona operações de gerenciamento, complete carrega tudo. Combine com --tools <service> ..., --read-only ou --permissions por serviço, e subtraia ferramentas individuais com --disabled-tools <name> ... — detalhes na documentação de modos do servidor.

Conecte Seu Cliente

Claude Desktop, web e mobile — execute o servidor em modo HTTP e adicione-o como um Connector (Configurações → Connectors → Adicionar conector personalizado). Este é o caminho recomendado; o guia de Connector tem capturas de tela passo a passo. A configuração legada via stdio permanece disponível para clientes sem suporte a Connector — consulte o FAQ.

Claude Code

# Start the server in HTTP mode, then:
claude mcp add --transport http workspace-mcp http://localhost:8000/mcp

# Optional: install the bundled skill for better Workspace tool routing
ln -s "$(pwd)/skills/managing-google-workspace" ~/.claude/skills/managing-google-workspace

ChatGPT — conecte via Developer Mode com o guia do ChatGPT.

VS Code, LM Studio, Open WebUI e todo o resto — qualquer cliente MCP funciona via HTTP transmitível (recomendado) ou stdio. Passo a passos específicos por cliente estão nos guias e no FAQ.

CLI

workspace-cli lista e chama ferramentas contra um servidor em execução com cache de tokens OAuth criptografado e persistido em disco — autentique uma vez, automatize para sempre:

uv run workspace-cli list
uv run workspace-cli call search_gmail_messages query="is:unread" max_results=5

Instale globalmente com uv tool install . a partir deste repositório. ⚠️ Não use uvx workspace-cli — um pacote PyPI abandonado ocupa esse nome.

Implantação e Configuração Avançada

Tudo o que você precisa para executar isso em produção está em dois lugares. A documentação cobre modos de autenticação e configuração do servidor:

• Autenticação multiusuário OAuth 2.1 — tokens de portador, necessários para endpoints HTTP remotos ou compartilhados
• Modo de contêiner sem estado — zero gravações em disco para implantações restritas
• Backends de armazenamento de proxy OAuth — memória, disco ou Valkey/Redis para configurações distribuídas
• Modo de provedor OAuth externo — traga seu próprio servidor de autenticação, valide apenas tokens de portador
• Contas de serviço com delegação em todo o domínio — personificação de usuário por solicitação com uma lista de permissões de domínio opcional
• Identidade de gateway confiável — isolamento por usuário verificado por proxy com Pomerium, Cloudflare Access, oauth2-proxy ou qualquer gateway verificável por JWKS
• Rastreamento OpenTelemetry — opcional, desativado a menos que você configure um endpoint OTLP
• Docker — docker build -t workspace-mcp . && docker run -p 8000:8000 workspace-mcp

O Guia de Implantação Avançada cobre especificidades de self-hosting: configuração de proxy reverso com WORKSPACE_EXTERNAL_URL (incluindo o workaround de consentimento Origin: null do nginx, a saída de emergência WORKSPACE_MCP_ALLOW_NULL_ORIGIN_CONSENT e a armadilha Referrer-Policy), validação de origem e allowlisting do webview do VS Code, backends de armazenamento de credenciais (diretório local ou GCS com imposição de CMEK), e a referência completa de variáveis de ambiente. No modo de provedor OAuth externo, o token ya29.* de cada requisição é verificado no endpoint userinfo do Google em um pool de workers dedicado, e uma requisição que encontra o pool cheio é rejeitada com 401 em vez de enfileirada. O pool é compartilhado por todos os chamadores do processo e tem como padrão 4 workers, então um gateway que atende muitos usuários deve aumentar WORKSPACE_MCP_TOKEN_VALIDATION_WORKERS para o número de chamadas de ferramentas concorrentes que espera. Valores inválidos ou não positivos fazem a inicialização do servidor falhar.

Defina WORKSPACE_MCP_TOKEN_VALIDATION_CACHE_TTL para um número de segundos para lembrar a identidade de cada token validado por esse período, de modo que chamadas repetidas com o mesmo token ignorem a ida e volta e não ocupem um worker de validação. Apenas um hash do token é mantido, e falhas nunca são armazenadas em cache. A compensação é que um token revogado ou expirado dentro do TTL ainda passa nessa verificação (o Google o rejeita na chamada real da API), então mantenha o TTL curto; valores acima de 300 são limitados a 300. Não definido ou 0 desativa o cache; valores inválidos ou negativos fazem a inicialização do servidor falhar.

Teto opcional de payload por download para implantações em contêineres: defina WORKSPACE_MCP_MAX_FILE_BYTES para uma contagem positiva de bytes (por exemplo, 5242880 para 5 MiB) para rejeitar downloads do Drive / Gmail / Chat / Google Docs que, de outra forma, seriam totalmente armazenados em buffer no processo. Não definido ou 0 deixa o tamanho total sem limite; transferências do Drive sem limite ainda usam blocos de transporte de 256 KiB em vez do padrão de 100 MiB do cliente Google. Este é um limite de tamanho de arquivo, não um limite de RSS do processo: deixe margem para parsing, representação base64/JSON e chamadas de ferramentas concorrentes. Valores inválidos ou negativos fazem a inicialização do servidor falhar em vez de desativar silenciosamente o limite. Downloads transmitidos diretamente para o disco não estão sujeitos a esse teto de payload em memória.

No modo stateless, que não tem armazenamento de anexos, get_drive_file_download_url retorna o próprio arquivo como um recurso incorporado. WORKSPACE_MCP_STATELESS_INLINE_MAX_BYTES limita esse arquivo inline (padrão 10 MiB; 0 desativa retornos inline), e ele nunca excede WORKSPACE_MCP_MAX_FILE_BYTES quando isso está definido. Valores inválidos ou negativos fazem a inicialização do servidor falhar.

Implantações hospedadas onde o servidor não pode ver o disco do chamador podem definir WORKSPACE_MCP_DISABLE_LOCAL_FILES=true. As ferramentas então param de anunciar parâmetros file_path do lado do servidor e recusam caminhos locais com orientação para passar uma URL ou conteúdo inline. O modo stateless implica essa configuração. Ela está desativada por padrão, inclusive para HTTP streamable, porque um servidor em localhost compartilha o sistema de arquivos do cliente.

Em tal servidor, uploads podem contorná-lo completamente: create_drive_file, update_drive_file e as ferramentas import_to_google_* aceitam return_upload_url=true, que abre uma sessão de upload retomável do Google Drive e retorna sua URL pré-autorizada. O cliente então PUT os bytes diretamente para o Google (sem cabeçalho Authorization), então arquivos grandes ou binários nunca passam pelo servidor MCP ou pelo contexto do modelo. As duas configurações são dois lados de um mesmo interruptor: return_upload_url é anunciado apenas quando WORKSPACE_MCP_DISABLE_LOCAL_FILES está definido (ou no modo stateless), e um servidor com acesso a arquivos locais o recusa, já que file_path é o caminho lá.

Arquivos do Office (.docx, .xlsx, .pptx) são arquivos ZIP, então o teto acima limita apenas seu tamanho compactado. A extração de texto aplica separadamente WORKSPACE_MCP_MAX_OFFICE_XML_BYTES (padrão 26214400, 25 MiB) como limites independentes no XML expandido e no texto UTF-8 extraído. Um arquivo além de qualquer um dos limites é relatado como grande demais para extrair. Esses limites limitam o tamanho de entrada e saída, não a memória do processo: a árvore XML analisada mediu aproximadamente 14 a 30 vezes o tamanho do XML, então reduza o valor em contêineres pequenos. 0 remove ambos os limites; valores inválidos ou negativos fazem a inicialização do servidor falhar.

Implantações avançadas de OAuth 2.1 afetadas por atualizações concorrentes de tokens do cliente podem ajustar o limite de atualização antecipada do FastMCP e o tempo de vida do token de acesso voltado ao cliente, e implantações que desejam limitar por quanto tempo os registros por login permanecem no backend de armazenamento do proxy OAuth podem encurtar o tempo de vida do token de atualização voltado ao cliente. Veja .env.oauth21 para as configurações limitadas, valores recomendados e compensações de segurança. As duas primeiras configurações reduzem a frequência com que a corrida ocorre; elas não adicionam um período de carência à rotação de token de atualização de uso único do FastMCP.

Melhores Práticas de Segurança

Por padrão, este servidor não envia dados para nenhum lugar, exceto para as APIs do Google, usando suas próprias credenciais de cliente OAuth - sem relatórios de uso, analytics, servidor de licença ou dependência de SaaS. Licenciado sob MIT, sem CLA, sem licenciamento duplo e sem copyleft na cadeia de dependências. A postura completa de segurança - minimização de escopo, bloqueio de caminhos sensíveis, modo stateless - está documentada em workspacemcp.com.

Algumas coisas que valem a pena internalizar antes de conectar um LLM ao seu e-mail:

• Injeção de prompt é real. E-mails, documentos e eventos podem conter instruções ocultas. Conecte apenas dados confiáveis a um LLM e seja deliberado sobre quais ferramentas de escrita você habilita.
• Nunca faça commit de .env, client_secret.json ou .credentials/ no controle de versão.
• Leituras de arquivos locais são isoladas no diretório de anexos gerenciado. Amplie com ALLOWED_FILE_DIRS apenas se você confiar no cliente e em suas fontes de dados; .env*, ~/.ssh/, ~/.aws/ e caminhos semelhantes são sempre bloqueados.
• Implantações de produção devem usar HTTPS e OAuth 2.1.

Desenvolvimento

uv sync --group dev    # install deps
uv run ruff check .    # lint
uv run pytest          # test

Módulos de serviço de arquivo único ficam em g<service>/, ferramentas são registradas com decoradores @server.tool e níveis são definidos em core/tool_tiers.yaml. PRs são bem-vindos.

Licença

MIT - veja LICENSE. A licença tem 21 linhas e diz o que significa.

Validações: