Google Workspace

Interaja com os serviços do Google Workspace, como Gmail e Google Agenda.

Documentação

Servidor MCP Google Workspace

Um servidor Model Context Protocol para serviços do Google Workspace. Este servidor fornece ferramentas para interagir com o Gmail e o Google Agenda através do protocolo MCP.

Recursos

Suporte a múltiplas contas do Google
- Usar e alternar entre várias contas do Google
- Cada conta pode ter metadados e descrições personalizados
Integração com o Gmail
- Consultar e-mails com pesquisa avançada
- Ler conteúdo completo de e-mails e anexos
- Criar e gerenciar rascunhos
- Responder a e-mails
- Arquivar e-mails
- Lidar com anexos
- Suporte a operações em lote
Integração com o Google Agenda
- Listar agendas disponíveis
- Visualizar eventos da agenda
- Criar novos eventos
- Excluir eventos
- Suporte a múltiplas agendas
- Suporte a fuso horário personalizado

Exemplos de Prompts

Experimente estes exemplos de prompts com seu assistente de IA:

Gmail

"Recupere minhas mensagens não lidas mais recentes"
"Pesquise meus e-mails do Scrum Master"
"Recupere todos os e-mails do departamento de contabilidade"
"Pegue o e-mail sobre ABC e resuma-o"
"Escreva uma resposta educada para o último e-mail da Alice e envie como rascunho"
"Responda ao e-mail do Bob com uma nota de agradecimento. Salve como rascunho"

Google Agenda

"O que tenho na minha agenda para amanhã?"
"Verifique a agenda da Família na minha conta privada para a próxima semana"
"Preciso planejar um evento com o Tim por 2 horas na próxima semana. Sugira alguns horários"

Pré-requisitos

Node.js >= 20
Um projeto no Google Cloud com as APIs do Gmail e do Google Agenda habilitadas
Credenciais OAuth 2.0 para as APIs do Google

Instalação

Clone o repositório:

git clone https://github.com/j3k0/mcp-google-workspace.git
cd mcp-google-workspace

Instale as dependências:
```
npm install
```
Compile o código TypeScript:
```
npm run build
```

Configuração

Configuração do OAuth 2.0

As APIs do Google Workspace (G Suite) exigem autorização OAuth2. Siga estas etapas para configurar a autenticação:

Crie as credenciais OAuth2:
- Acesse o Google Cloud Console
- Crie um novo projeto ou selecione um existente
- Habilite a API do Gmail e a API do Google Agenda para o seu projeto
- Vá em "Credenciais" → "Criar credenciais" → "ID do cliente OAuth"
- Selecione "Aplicativo de desktop" ou "Aplicativo web" como tipo de aplicativo
- Configure a tela de consentimento OAuth com as informações necessárias
- Adicione URIs de redirecionamento autorizados (inclua http://localhost:4100/code para desenvolvimento local)

Escopos OAuth2 necessários:

[
  "openid",
  "https://mail.google.com/",
  "https://www.googleapis.com/auth/gmail.settings.basic",
  "https://www.googleapis.com/auth/calendar",
  "https://www.googleapis.com/auth/userinfo.email"
]

Crie um arquivo .gauth.json na raiz do projeto com suas credenciais do Google OAuth 2.0:

{
  "installed": {
    "client_id": "your_client_id",
    "project_id": "your_project_id",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
    "client_secret": "your_client_secret",
    "redirect_uris": ["http://localhost:4100/code"]
  }
}

Crie um arquivo .accounts.json para especificar quais contas do Google podem usar o servidor:
```
{
  "accounts": [
    {
      "email": "your.email@gmail.com",
      "account_type": "personal",
      "extra_info": "Primary account with Family Calendar"
    }
  ]
}
```
Você pode especificar várias contas. Certifique-se de que elas tenham acesso no seu aplicativo Google Auth. O campo extra_info é especialmente útil, pois você pode adicionar informações que deseja informar à IA sobre a conta (por exemplo, se ela possui uma agenda específica).

Autenticar

Depois que .gauth.json e .accounts.json estiverem configurados, autentique suas contas:

npm run authenticate

Isso abre um navegador para cada conta configurada concluir o fluxo de consentimento OAuth. O script aguarda até 5 minutos por conta para o callback.

# Authenticate a specific account
npm run authenticate -- user@gmail.com

# Force re-authentication (e.g. after OAuth scope changes)
npm run authenticate -- user@gmail.com --force

# Custom config paths (same flags as the server)
npm run authenticate -- --gauth-file /path/to/.gauth.json --accounts-file /path/to/.accounts.json

Se instalado via npm, você também pode executar:

npx mcp-gmail-authenticate

Configuração do Claude Desktop

Configure o Claude Desktop para usar o servidor mcp-google-workspace:

No MacOS: Edite ~/Library/Application\ Support/Claude/claude_desktop_config.json

No Windows: Edite %APPDATA%/Claude/claude_desktop_config.json

Configuração de Servidores Não Publicados (Desenvolvimento)

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "<dir_to>/mcp-google-workspace/launch"
    }
  }
}

Configuração de Servidores Publicados

{
  "mcpServers": {
    "mcp-google-workspace": {
      "command": "npx",
      "args": [
        "mcp-google-workspace"
      ]
    }
  }
}

Docker

Você também pode construir e executar o servidor MCP no Docker:

docker build -t mcp-google-workspace .
docker run --rm -i \
  -v "$PWD/.gauth.json:/app/.gauth.json:ro" \
  -v "$PWD/.accounts.json:/app/.accounts.json:ro" \
  -v "$PWD/.credentials:/app/.credentials" \
  -e GMAIL_ALLOW_DRAFTS=true \
  -e GMAIL_ATTACHMENTS_DIR=/app/attachments \
  mcp-google-workspace \
  node dist/server.js --credentials-dir /app/.credentials

Não inclua .gauth.json, .accounts.json, tokens OAuth ou arquivos .env na imagem. O .dockerignore incluído exclui esses arquivos; monte-os em tempo de execução.

Uso

Inicie o servidor:
```
npm start
```
Argumentos opcionais:
- --gauth-file: Caminho para o arquivo de credenciais OAuth2 (padrão: ./.gauth.json)
- --accounts-file: Caminho para o arquivo de configuração de contas (padrão: ./.accounts.json)
- --credentials-dir: Diretório para armazenar credenciais OAuth (padrão: diretório atual)
O servidor iniciará e aguardará comandos MCP via stdin/stdout.
Na primeira execução para cada conta, ele irá:
- Abrir uma janela do navegador para autenticação OAuth2
- Ouvir na porta 4100 para o callback OAuth2
- Armazenar as credenciais para uso futuro em um arquivo chamado .oauth2.{email}.json

Variáveis de Ambiente

GMAIL_ALLOW_SENDING — defina como true para permitir que gmail_send realmente envie e-mails. Padrão: desabilitado.
GMAIL_ALLOW_DRAFTS — defina como true para permitir ferramentas de criação de rascunhos. Padrão: desabilitado.
GMAIL_ATTACHMENTS_DIR — diretório base sob o qual gmail_get_attachment e gmail_bulk_save_attachments podem gravar arquivos. Caminhos de anexos fornecidos pelo chamador são tratados como relativos a este diretório; caminhos absolutos, travessia de diretório e symlinks que escapam do diretório são rejeitados. Padrão: ~/.mcp-gsuite/attachments.

Ferramentas Disponíveis

Gerenciamento de Contas

gmail_list_accounts / calendar_list_accounts
- Listar todas as contas do Google configuradas
- Visualizar metadados e descrições das contas
- Nenhum user_id necessário

Ferramentas do Gmail

gmail_query_emails
- Pesquisar e-mails com a sintaxe de consulta do Gmail (ex.: 'is:unread', 'from:example@gmail.com', 'newer_than:2d', 'has:attachment')
- Retorna e-mails em ordem cronológica reversa
- Inclui metadados e resumo do conteúdo
gmail_get_email
- Recuperar conteúdo completo do e-mail por ID
- Inclui corpo completo da mensagem e informações de anexos
gmail_bulk_get_emails
- Recuperar vários e-mails por ID em uma única solicitação
- Eficiente para processamento em lote
gmail_create_draft
- Criar novos rascunhos de e-mail
- Suporte a destinatários em cópia (CC)
gmail_delete_draft
- Excluir rascunhos de e-mail por draft_id
- Nota: draft_id é distinto do ID da mensagem retornado por gmail_query_emails. Use gmail_list_drafts para obtê-lo.
gmail_list_drafts
- Listar rascunhos do Gmail, opcionalmente filtrados por uma consulta de pesquisa do Gmail
- Retorna o draft_id de cada rascunho (necessário para gmail_delete_draft) junto com seu message_id, assunto, destinatários e trecho
gmail_reply
- Responder a e-mails existentes
- Opção de enviar imediatamente ou salvar como rascunho
- Suporte a "Responder a todos" via CC
gmail_get_attachment
- Baixar anexos de e-mail
- Salvar no disco ou retornar como recurso incorporado
gmail_bulk_save_attachments
- Salvar vários anexos em uma única operação
gmail_archive / gmail_bulk_archive
- Mover e-mails para fora da caixa de entrada
- Suporte a operações individuais ou em lote

Ferramentas do Google Agenda

calendar_list
- Listar todas as agendas acessíveis
- Inclui metadados da agenda, papéis de acesso e informações de fuso horário
calendar_get_events
- Recuperar eventos em um intervalo de datas
- Suporte a múltiplas agendas
- Opções de filtro (eventos excluídos, máximo de resultados)
- Personalização de fuso horário
calendar_create_event
- Criar novos eventos de agenda
- Suporte a participantes e notificações
- Campos de local e descrição
- Tratamento de fuso horário
calendar_delete_event
- Excluir eventos por ID
- Opção para notificações de cancelamento

Desenvolvimento

O código-fonte está em TypeScript no diretório src/
A saída da compilação vai para o diretório dist/
Usa módulos ES para melhor modularidade
Segue as melhores práticas da API do Google

Estrutura do Projeto

mcp-google-workspace/
├── src/
│   ├── server.ts           # Main server implementation
│   ├── services/
│   │   └── gauth.ts        # Google authentication service
│   ├── tools/
│   │   ├── gmail.ts        # Gmail tools implementation
│   │   └── calendar.ts     # Calendar tools implementation
│   └── types/
│       └── tool-handler.ts # Common types and interfaces
├── .gauth.json             # OAuth2 credentials
├── .accounts.json          # Account configuration
├── package.json            # Project dependencies
└── tsconfig.json           # TypeScript configuration

Comandos de Desenvolvimento

npm run build: Compilar código TypeScript
npm start: Iniciar o servidor
npm run dev: Iniciar em modo de desenvolvimento com recarga automática

Contribuindo

Faça um fork do repositório
Crie um branch de recurso
Faça commit das suas alterações
Envie para o branch
Crie um Pull Request

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes