mcp-google-chat

Google Chat MCP

Inglês | Русский

A1 Google Chat MCP permite que um aplicativo de IA trabalhe no Google Chat em linguagem natural. Encontre o espaço ou a mensagem direta certa, acompanhe uma conversa, responda em um tópico, reaja com um emoji e gerencie quem está em um espaço.

Ele usa a API do Google Chat com sua conta do Google e age como o usuário conectado: as mensagens são enviadas em seu nome, e apenas suas próprias mensagens e reações podem ser editadas ou excluídas. Ele torna explícitos os limites da API do Chat em vez de sugerir que toda tarefa de chat é possível.

• 20 ferramentas. Conecte-se a partir do chat, descubra espaços e mensagens diretas, leia e envie mensagens com controle de tópicos, gerencie reações com emojis, leia metadados de anexos e gerencie associações.
• Conecta-se a partir da conversa. Diga "conectar Google Chat": o servidor guia você pelo cliente OAuth, captura o redirecionamento do Google em 127.0.0.1 com PKCE e guarda os tokens ele mesmo — sem arquivos de configuração, sem reiniciar.
• Você age como você mesmo. Os envios aparecem em seu nome; edições e exclusões se limitam às suas próprias mensagens e reações.
• Um envio nunca é repetido. Após uma falha ambígua, o servidor não tenta reenviar uma escrita — um envio repetido seria uma mensagem duplicada em uma sala real.
• Escopos mínimos do Google. O servidor envia qualquer token que você emitir; conceda escopos por tarefa — somente leitura é suficiente para navegar por espaços e mensagens.

Comece com uma pergunta somente leitura:

Mostre as mensagens de hoje no espaço da equipe e resuma o que foi decidido.

Conectar o servidor · Explorar casos de uso · Abrir documentação técnica

Veja funcionando em um minuto

Você: O que foi discutido no espaço de release hoje?

Assistente: Lista as mensagens de hoje com remetentes e tópicos. Nada é alterado.

Você: Responda no tópico de deploy que a implantação está concluída.

Assistente: Mostra o espaço de destino, o tópico e o texto rascunhado, e então pede confirmação antes de enviar.

Você: Confirmar.

Assistente: Envia a resposta em seu nome naquele tópico. Não toca em nenhuma outra mensagem.

Conteúdo

• Início rápido
• O que você pode pedir para ele fazer
• Como o servidor age no Chat
• O que pode mudar
• Obtendo acesso
• Configuração
• Dados, limites e trabalho em segundo plano
• Documentação técnica
• Suporte

Início rápido

Você precisa do Node.js 20+ e de uma conta do Google com acesso ao Google Chat. As credenciais não são necessárias na instalação — o servidor conecta-se a partir da conversa.

1. Adicione o servidor ao seu aplicativo de IA.
2. Diga "conectar Google Chat": o assistente guia você pela criação do cliente OAuth e aprovação do acesso sem editar arquivos de configuração ou reiniciar.
3. Faça a pergunta somente leitura acima.

codex mcp add google-chat \
  -- npx -y mcp-google-chat@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-chat \
  -- npx -y mcp-google-chat@latest

claude mcp list

{
  "mcpServers": {
    "google-chat": {
      "command": "npx",
      "args": ["-y", "mcp-google-chat@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-chat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-chat@latest"]
    }
  }
}

{
  "servers": {
    "google-chat": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-chat@latest"]
    }
  }
}

O que você pode pedir para ele fazer

Acompanhar uma conversa

• Mostre meus espaços e encontre a mensagem direta com alex@example.com.
• O que foi postado no espaço de release hoje? Resuma as decisões.
• Mostre todo o tópico ao qual esta mensagem pertence.

Postar e manter mensagens

• Envie uma atualização de status para o espaço da equipe.
• Responda no tópico de deploy que a implantação está concluída.
• Corrija o erro de digitação na minha última mensagem, ou exclua-a completamente.

Reagir e verificar anexos

• Adicione um 👍 ao anúncio e mostre quem mais reagiu e com o quê.
• Remova minha reação daquela mensagem.
• Quais arquivos estão anexados a esta mensagem? Mostre seus nomes e tipos.

Gerenciar quem está em um espaço

• Quem está neste espaço e quem são os gerentes?
• Adicione alex@example.com ao espaço e torne-o gerente.
• Remova um ex-colega de equipe do espaço.

Como o servidor age no Chat

1. Com as credenciais de atualização OAuth, o servidor age como o usuário conectado: as mensagens são enviadas em seu nome, e edições e exclusões alcançam apenas suas próprias mensagens e reações. Alterações de associação também exigem que você seja gerente do espaço.
2. Espaços aceitam um id simples, mas mensagens, tópicos, membros, reações e anexos são endereçados pelos nomes completos de recursos que a API retorna — liste primeiro, depois aja sobre um nome exato.
3. Uma resposta tem como alvo um tópico pelo nome ou por uma chave de tópico. Por padrão, um envio recorre a iniciar um novo tópico quando o destino não pode ser encadeado; você pode pedir para falhar nesse caso.
4. Agir como um aplicativo do Chat — cards, mensagens diretas de aplicativo, o endpoint dedicado de anexos, exclusões forçadas — é uma configuração separada do Google Cloud; a única ponte aqui é um token de acesso de conta de serviço fornecido como GOOGLE_CHAT_ACCESS_TOKEN.

A API do Chat não pode pesquisar texto de mensagens — os únicos filtros de mensagem são tempo de criação e tópico. find_direct_message encontra um DM existente, mas nunca cria um, e bytes de arquivo não são baixados ou enviados por este servidor. A criação de espaços e os outros métodos de API não cobertos passam por raw_request.

O que pode mudar

O cliente de IA controla os prompts de confirmação. O servidor marca ferramentas de leitura, escrita e destrutivas para que o cliente possa distinguir acompanhar de postar.

Obtendo acesso

O Google Chat exige OAuth 2.0; uma chave de API não é suficiente. Há dois caminhos, e o primeiro não precisa de arquivos de configuração.

Conectar pelo chat (recomendado)

Diga "conectar Google Chat" e o assistente executa o fluxo com você:

1. setup_instructions imprime a lista de verificação: criar ou selecionar um projeto do Google Cloud, ativar a API Google Chat, configurar a tela de consentimento e criar um cliente OAuth de aplicativo de desktop.
2. Baixe o JSON desse cliente ("Baixar JSON") e dê ao assistente o caminho — set_client o armazena com acesso apenas do proprietário. O segredo nunca passa pela conversa.
3. start_login retorna um link de consentimento do Google. Abra-o nesta máquina e aprove; o código volta para um listener de uso único em 127.0.0.1 (PKCE), nunca pelo chat.
4. finish_login troca o código, salva os tokens em ~/.config/mcp-google-chat/credentials.json (modo 0600) e os verifica com uma chamada real à API do Chat — assim, uma API do Chat ainda desativada é detectada ali mesmo, não na sua primeira pergunta real.

Os tokens são relidos a cada chamada, então a conexão funciona imediatamente — sem reiniciar o aplicativo de IA. auth_status mostra o que está conectado, logout revoga e exclui. O login pede chat.spaces.readonly, chat.messages, chat.messages.reactions e chat.memberships.readonly; o escopo de administrador por trás de search_spaces não é solicitado — use o caminho de variáveis de ambiente se precisar dele.

Variáveis de ambiente (CI, instalações não assistidas)

1. Crie ou selecione um projeto do Google Cloud e ative a API Google Chat.

2. Configure a tela de consentimento OAuth e crie um cliente OAuth de aplicativo de desktop.

3. Autorize a conta do Google pela qual você conversa. O OAuth 2.0 Playground pode obter o token de atualização quando Usar minhas próprias credenciais OAuth estiver ativado.

4. Solicite apenas os escopos que suas sessões precisam. Para leitura e envio, isto é suficiente:

   https://www.googleapis.com/auth/chat.spaces.readonly
   https://www.googleapis.com/auth/chat.messages.readonly
   https://www.googleapis.com/auth/chat.messages.create
   

   A tabela completa por tarefa — editar e excluir suas próprias mensagens, reações, associações, pesquisa administrativa — está em docs/TOOLS.md.

Tokens de atualização OAuth em modo de teste podem expirar após sete dias. Publique o aplicativo OAuth, ou use um aplicativo Interno em um domínio do Workspace, quando precisar de acesso de longa duração. Trate o segredo do cliente e o token de atualização como senhas.

Para uma sessão rápida, um token de curta duração em GOOGLE_CHAT_ACCESS_TOKEN também funciona — por exemplo, de gcloud auth print-access-token com escopos do Chat concedidos. A mesma variável é como um token de aplicativo do Chat de conta de serviço chega ao servidor quando você precisa de recursos exclusivos de aplicativo.

Configuração

Toda variável é opcional — sem nenhuma delas, o servidor conecta-se pelo chat.

* Para o caminho de variáveis de ambiente, forneça o trio OAuth ou um token de acesso. Quando definidos, eles têm precedência sobre um login armazenado pelo chat e o servidor nunca os atualiza ou exclui.

Iniciado sem nenhuma credencial, o servidor ainda completa o handshake MCP; as instruções e a primeira chamada de ferramenta então nomeiam ambas as correções — o login pelo chat (sem reiniciar) e as variáveis de ambiente (reiniciar).

Dados, limites e trabalho em segundo plano

• As solicitações vão para o Google Chat. O servidor local atualiza os tokens OAuth do Google e chama a API do Chat; o token nunca é enviado para nenhum outro host. Sua telemetria anônima contém um ID de instalação, versão do pacote, cliente de IA e versões de plataforma, e nomes de ferramentas — nunca tokens OAuth, conteúdo de mensagens, argumentos de ferramentas ou prompts. Defina ASKADS_TELEMETRY=0 para optar por não participar.
• O Google aplica cotas por projeto e por usuário. Em 429, o servidor usa backoff; leituras também tentam novamente após erros de rede e 5xx, enquanto gravações nunca são repetidas após uma falha incerta — um envio repetido seria uma mensagem duplicada em uma sala real. send_message aceita um ID de mensagem personalizado que torna um envio endereçável e deduplicável.
• Não há polling em segundo plano. O servidor só é executado quando chamado. list_messages pode consultar um espaço incrementalmente por tempo de criação se seu aplicativo de IA suportar tarefas agendadas; assinaturas de eventos de espaço passam por raw_request.

Documentação técnica

• Catálogo de capacidades do MCP — páginas orientadas a tarefas para cada ferramenta.
• Todas as ferramentas e entradas
• Documentação de desenvolvimento
• Documentação de publicação
• Referência da API do Google Chat

Suporte

Encontrou um bug ou precisa de um cenário? Crie um problema ou escreva no Telegram.

Você chegou ao fim!