Google MCP

Um servidor MCP all-in-one do Google Workspace

Documentação

Google MCP Server

Um servidor abrangente de Model Context Protocol (MCP) para integração com o Google, fornecendo acesso a Google Calendar, Docs, Sheets, Slides, Drive, Gmail, Contacts, YouTube, Tasks, Forms, Chat e Meet.

Recursos

Google Forms

Criar e gerenciar Google Forms
Adicionar perguntas (múltipla escolha, resposta curta, caixas de seleção, etc.)
Adicionar quebras de página, itens de texto, imagens e vídeos
Listar e recuperar respostas de formulários
Atualizar configurações do formulário (modo de quiz, etc.)

Google Chat

Listar, criar e gerenciar espaços do Chat
Enviar, atualizar e excluir mensagens
Adicionar e remover reações
Gerenciar membros do espaço
Suporte a tópicos para conversas

Google Meet

Criar espaços de reunião com controles de acesso
Agendar reuniões via integração com o Calendar
Criar reuniões instantâneas
Listar e acessar registros de conferências
Visualizar informações dos participantes
Acessar gravações e transcrições de reuniões

Google Calendar

Listar calendários e eventos
Criar, atualizar e excluir eventos
Adicionar eventos rapidamente usando linguagem natural
Obter eventos de hoje e eventos futuros
Verificar disponibilidade livre/ocupado

Google Gmail

Ler, pesquisar e listar e-mails
Enviar e-mails e responder a tópicos, com anexos de arquivos
Listar e baixar anexos de mensagens recebidas
Marcar como lido/não lido, mover mensagens para a lixeira
Listar rótulos e organizar e-mails

Google Contacts (API People)

Listar, pesquisar e gerenciar contatos
Criar, atualizar e excluir contatos
Listar grupos de contatos

Google Drive

Listar, pesquisar e navegar por arquivos e pastas
Enviar, baixar, copiar, mover e excluir arquivos, texto ou binário
Substituir o conteúdo de um arquivo existente
Exportar arquivos do Google Workspace para outros formatos (PDF, DOCX, CSV, ...)
Criar pastas
Renomear arquivos

Google Docs

Criar novos documentos com conteúdo inicial opcional
Ler o conteúdo do documento
Inserir e anexar texto
Localizar e substituir texto
Listar todos os documentos

Google Sheets

Criar planilhas com várias abas
Ler valores de intervalos
Atualizar e anexar valores
Limpar intervalos
Adicionar e excluir abas
Listar todas as planilhas

Google Slides

Criar e gerenciar apresentações
Adicionar, excluir e duplicar slides
Adicionar caixas de texto e imagens
Localizar e substituir texto
Listar todas as apresentações

Google YouTube

Pesquisar vídeos, canais e playlists
Obter detalhes de vídeos e canais
Visualizar e gerenciar playlists
Obter comentários de vídeos
Visualizar inscrições e vídeos curtidos
Avaliar vídeos

Google Tasks (Alternativa ao Keep)

Gerenciar listas de tarefas (semelhante às categorias do Keep)
Criar, atualizar, concluir e excluir tarefas
Tarefas suportam notas/descrições (semelhante às notas do Keep)
Ferramentas de "notas" convenientes que fornecem funcionalidade semelhante ao Keep

Observação: O Google Keep não possui uma API pública oficial. Este servidor usa a API Google Tasks como alternativa, que fornece capacidades semelhantes de anotações por meio de tarefas com descrições.

Instalação

# Clone the repository
cd google-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

Configuração do Google Cloud

Antes de usar este servidor, você precisa configurar as credenciais do Google Cloud:

1. Criar um Projeto no Google Cloud

Acesse o Console do Google Cloud
Crie um novo projeto ou selecione um existente
Ative as seguintes APIs:
- Google Calendar API
- Google Docs API
- Google Sheets API
- Google Slides API
- Google Drive API
- Gmail API
- People API (Contacts)
- YouTube Data API v3
- Google Tasks API
- Google Forms API
- Google Chat API
- Google Meet REST API

2. Criar Credenciais OAuth 2.0

Navegue até APIs & Services > Credentials
Clique em Create Credentials > OAuth client ID
Selecione Desktop app como o tipo de aplicativo
Baixe o arquivo JSON

3. Colocar o Arquivo de Credenciais

Salve o arquivo JSON baixado como credentials.json no local apropriado para sua plataforma:

Linux:

~/.config/google-mcp/credentials.json

(ou $XDG_CONFIG_HOME/google-mcp/credentials.json se XDG_CONFIG_HOME estiver definido)

macOS:

~/Library/Application Support/google-mcp/credentials.json

Windows:

%APPDATA%\google-mcp\credentials.json

(geralmente C:\Users\<username>\AppData\Roaming\google-mcp\credentials.json)

O arquivo deve ter a seguinte aparência:

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "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:3000/oauth2callback"]
  }
}

Uso com Clientes MCP

O servidor é executado como um worker de pool de longa duração, não como um subprocesso stdio. Ele expõe o transporte atual Streamable HTTP em /mcp e mantém o transporte legado HTTP+SSE em /sse além de /messages para clientes mais antigos. Inicie o worker uma vez e, em seguida, aponte os clientes para /mcp.

Inicie o worker:

node /path/to/google-mcp/dist/index.js
# or from the project directory:
pnpm dev

Ele escuta em 127.0.0.1:3015 por padrão. Substitua com GOOGLE_MCP_HOST e GOOGLE_MCP_PORT (ou PORT).

Adicione à sua configuração de configurações MCP:

{
  "mcpServers": {
    "google": {
      "url": "http://127.0.0.1:3015/mcp"
    }
  }
}

Cada cliente que se conecta obtém sua própria sessão MCP enquanto compartilha uma sessão autenticada do Google, então você só completa o fluxo OAuth uma vez, não importa quantos clientes ou agentes se conectem. Clientes SSE legados podem continuar a usar http://127.0.0.1:3015/sse.

Autenticação

No primeiro uso, chame a ferramenta google_auth para iniciar a autenticação OAuth:

O servidor fornecerá uma URL para autenticar
Abra a URL em um navegador e faça login com sua conta do Google
Conceda as permissões solicitadas
A autenticação será concluída automaticamente

Os tokens são armazenados localmente e serão atualizados automaticamente:

Linux: ~/.local/share/google-mcp/tokens.json (ou $XDG_DATA_HOME/google-mcp/)
macOS: ~/Library/Application Support/google-mcp/tokens.json
Windows: %APPDATA%\google-mcp\tokens.json

Arquivos Locais

Ferramentas que leem um arquivo local (path) ou gravam um (savePath) resolvem cada caminho dentro de um único diretório sandbox, com padrão para ~/Downloads/google-mcp. Caminhos relativos são considerados a partir dessa raiz; caminhos absolutos devem estar dentro dela.

Isso é importante porque os argumentos vêm de um modelo que pode ter acabado de ler um e-mail hostil. Sem um limite, um "anexar ~/.ssh/id_rsa" injetado é uma primitiva de exfiltração e um savePath injetado de ~/.ssh/authorized_keys é execução de código. Dentro da sandbox, ambos são inertes.

export GOOGLE_MCP_FILE_ROOT="$HOME/Documents/mcp-files"

Independentemente da raiz, o servidor se recusa a tocar em diretórios de chaves e credenciais (.ssh, .aws, .gnupg, ...) ou arquivos que parecem segredos (*.pem, *.key, tokens.json, credentials.json, .env*), não segue symlinks para fora da raiz e nunca sobrescreve um arquivo existente.

Transferências inline são limitadas a 1 MB, pois caem no contexto do modelo; passe savePath para qualquer coisa maior, até 25 MB.

Ferramentas Disponíveis

Autenticação

Ferramenta	Descrição
`google_auth`	Iniciar autenticação OAuth
`google_auth_status`	Verificar status da autenticação
`google_auth_code`	Definir código de autenticação manualmente
`google_logout`	Sair e limpar tokens

Google Calendar

Ferramenta	Descrição
`calendar_list`	Listar todos os calendários
`calendar_get`	Obter detalhes do calendário
`calendar_list_events`	Listar eventos do calendário
`calendar_get_event`	Obter detalhes do evento
`calendar_create_event`	Criar novo evento
`calendar_update_event`	Atualizar evento existente
`calendar_delete_event`	Excluir um evento
`calendar_quick_add`	Adicionar evento via linguagem natural
`calendar_get_freebusy`	Verificar disponibilidade
`calendar_today`	Obter eventos de hoje
`calendar_upcoming`	Obter eventos futuros

Google Gmail

Ferramenta	Descrição
`gmail_get_profile`	Obter informações do perfil do Gmail
`gmail_list_labels`	Listar rótulos do Gmail
`gmail_list_messages`	Listar e-mails
`gmail_get_message`	Obter e-mail específico
`gmail_send`	Enviar um e-mail
`gmail_reply`	Responder a um e-mail
`gmail_get_attachment`	Baixar um anexo de uma mensagem
`gmail_trash`	Mover para a lixeira
`gmail_mark_read`	Marcar como lido
`gmail_mark_unread`	Marcar como não lido
`gmail_search`	Pesquisar e-mails
`gmail_get_unread`	Obter e-mails não lidos
`gmail_get_thread`	Obter tópico de e-mail

Google Contacts

Ferramenta	Descrição
`contacts_list`	Listar contatos
`contacts_get`	Obter detalhes do contato
`contacts_search`	Pesquisar contatos
`contacts_create`	Criar contato
`contacts_delete`	Excluir contato
`contacts_list_groups`	Listar grupos de contatos

Google Drive

Ferramenta	Descrição
`drive_list_files`	Listar arquivos com filtragem
`drive_get_file`	Obter metadados do arquivo
`drive_download_file`	Baixar conteúdo do arquivo, texto ou binário
`drive_upload_file`	Enviar um novo arquivo
`drive_update_file`	Substituir o conteúdo de um arquivo existente
`drive_delete_file`	Excluir um arquivo
`drive_create_folder`	Criar uma nova pasta
`drive_search`	Pesquisar arquivos por conteúdo
`drive_move_file`	Mover arquivo para pasta
`drive_copy_file`	Copiar um arquivo
`drive_rename_file`	Renomear um arquivo

Google Docs

Ferramenta	Descrição
`docs_create`	Criar um novo documento
`docs_read`	Ler o conteúdo do documento
`docs_insert_text`	Inserir texto em uma posição
`docs_append_text`	Anexar texto ao final
`docs_replace_text`	Localizar e substituir texto
`docs_list`	Listar todos os documentos

Google Sheets

Ferramenta	Descrição
`sheets_create`	Criar planilha
`sheets_get`	Obter informações da planilha
`sheets_read`	Ler valores de um intervalo
`sheets_update`	Atualizar valores em um intervalo
`sheets_append`	Anexar linhas
`sheets_clear`	Limpar um intervalo
`sheets_add_sheet`	Adicionar uma nova aba
`sheets_delete_sheet`	Excluir uma aba
`sheets_list`	Listar todas as planilhas

Google Slides

Ferramenta	Descrição
`slides_create`	Criar apresentação
`slides_get`	Obter apresentação
`slides_list`	Listar apresentações
`slides_add_slide`	Adicionar um slide
`slides_delete_slide`	Excluir um slide
`slides_add_text`	Adicionar caixa de texto
`slides_add_image`	Adicionar imagem
`slides_replace_text`	Localizar/substituir texto
`slides_duplicate_slide`	Duplicar slide

Google YouTube

Ferramenta	Descrição
`youtube_search`	Pesquisar no YouTube
`youtube_get_video`	Obter detalhes do vídeo
`youtube_get_channel`	Obter detalhes do canal
`youtube_get_my_channel`	Obter seu canal
`youtube_list_playlists`	Listar suas playlists
`youtube_get_playlist_items`	Obter vídeos da playlist
`youtube_get_video_comments`	Obter comentários do vídeo
`youtube_list_subscriptions`	Listar inscrições
`youtube_list_liked_videos`	Listar vídeos curtidos
`youtube_rate_video`	Curtir/não curtir vídeo

Google Tasks

Ferramenta	Descrição
`tasks_list_tasklists`	Listar listas de tarefas
`tasks_create_tasklist`	Criar lista de tarefas
`tasks_delete_tasklist`	Excluir lista de tarefas
`tasks_list_tasks`	Listar tarefas
`tasks_create_task`	Criar uma tarefa
`tasks_update_task`	Atualizar uma tarefa
`tasks_delete_task`	Excluir uma tarefa
`tasks_complete_task`	Marcar tarefa como concluída

Notas (semelhante ao Keep)

Ferramenta	Descrição
`notes_create`	Criar uma nota rápida
`notes_list`	Listar todas as notas
`notes_update`	Atualizar uma nota
`notes_delete`	Excluir uma nota

Google Forms

Ferramenta	Descrição
`forms_create`	Criar um novo formulário
`forms_get`	Obter detalhes do formulário
`forms_update_info`	Atualizar título/descrição
`forms_add_question`	Adicionar uma pergunta
`forms_delete_item`	Excluir item do formulário
`forms_list_responses`	Listar respostas do formulário
`forms_get_response`	Obter resposta específica
`forms_add_page_break`	Adicionar quebra de página
`forms_add_text`	Adicionar item de texto
`forms_add_image`	Adicionar imagem
`forms_add_video`	Adicionar vídeo do YouTube

Google Chat

Ferramenta	Descrição
`chat_list_spaces`	Listar espaços do Chat
`chat_get_space`	Obter detalhes do espaço
`chat_create_space`	Criar um espaço
`chat_delete_space`	Excluir um espaço
`chat_list_messages`	Listar mensagens
`chat_get_message`	Obter detalhes da mensagem
`chat_send_message`	Enviar uma mensagem
`chat_update_message`	Atualizar uma mensagem
`chat_delete_message`	Excluir uma mensagem
`chat_list_members`	Listar membros do espaço
`chat_add_member`	Adicionar um membro
`chat_remove_member`	Remover um membro
`chat_add_reaction`	Adicionar reação com emoji

Google Meet

Ferramenta	Descrição
`meet_create_space`	Criar espaço de reunião
`meet_get_space`	Obter detalhes do espaço
`meet_end_conference`	Encerrar reunião ativa
`meet_schedule`	Agendar uma reunião
`meet_create_instant`	Criar reunião instantânea
`meet_get_by_event`	Obter reunião a partir do evento
`meet_list_upcoming`	Listar próximas reuniões
`meet_list_conference_records`	Listar reuniões passadas
`meet_get_conference_record`	Obter gravação da reunião
`meet_list_participants`	Listar participantes
`meet_list_recordings`	Listar gravações
`meet_get_recording`	Obter gravação
`meet_list_transcripts`	Listar transcrições
`meet_get_transcript`	Obter transcrição
`meet_list_transcript_entries`	Obter texto da transcrição

Exemplos

Enviar um E-mail

Use gmail_send with to "recipient@example.com", subject "Hello", and body "This is a test email."

Criar um Evento no Calendário

Use calendar_create_event with summary "Team Meeting", startDateTime "2025-01-15T10:00:00-05:00", and endDateTime "2025-01-15T11:00:00-05:00"

Pesquisar no YouTube

Use youtube_search with query "MCP tutorial" and type "video"

Criar um Google Doc

Use docs_create with title "Meeting Notes" and content "# Weekly Meeting\n\nAttendees: ..."

Ler uma Planilha

Use sheets_read with spreadsheetId "abc123" and range "Sheet1!A1:D10"

Pesquisar no Drive

Use drive_search with query "quarterly report"

Criar uma Nota

Use notes_create with title "Shopping List" and content "- Milk\n- Eggs\n- Bread"

Criar um Google Formulário

Use forms_create with title "Customer Survey" and description "Help us improve our service"

Enviar uma Mensagem no Chat

Use chat_send_message with spaceName "spaces/AAAAA" and text "Hello team!"

Agendar um Google Meet

Use meet_schedule with summary "Team Standup", startTime "2025-01-15T09:00:00-05:00", and endTime "2025-01-15T09:30:00-05:00"

Desenvolvimento

# Run in development mode with hot reload
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

Licença

Licença MIT - consulte LICENSE para detalhes.

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.