mcp-google-chat

Google Chat MCP

Español | Русский

A1 Google Chat MCP permite que una aplicación de IA trabaje en Google Chat en lenguaje natural. Encuentra el espacio o mensaje directo correcto, ponte al día en una conversación, responde en un hilo, reacciona con un emoji y gestiona quién está en un espacio.

Utiliza la API de Google Chat con tu cuenta de Google y actúa como el usuario con sesión iniciada: los mensajes se envían bajo tu nombre, y solo tus propios mensajes y reacciones pueden editarse o eliminarse. Hace explícitos los límites de la API de Chat en lugar de dar a entender que cada tarea de chat es posible.

• 20 herramientas. Conéctate desde el chat, descubre espacios y mensajes directos, lee y envía mensajes con control de hilos, gestiona reacciones con emojis, lee metadatos de archivos adjuntos y gestiona membresías.
• Se conecta desde la conversación. Di "conectar Google Chat": el servidor te guía a través del cliente OAuth, captura la redirección de Google en 127.0.0.1 con PKCE y guarda los tokens él mismo — sin archivos de configuración, sin reinicios.
• Actúas como tú mismo. Los envíos aparecen bajo tu nombre; las ediciones y eliminaciones se limitan a tus propios mensajes y reacciones.
• Un envío nunca se reproduce. Después de un fallo ambiguo, el servidor no reintenta una escritura — un envío reproducido sería un mensaje duplicado en una sala real.
• Ámbitos de Google mínimos. El servidor envía cualquier token que hayas generado; concede ámbitos según la tarea — los de solo lectura son suficientes para explorar espacios y mensajes.

Comienza con una pregunta de solo lectura:

Muestra los mensajes de hoy en el espacio del equipo y resume lo que se decidió.

Conectar el servidor · Explorar casos de uso · Abrir documentación técnica

Véalo funcionar en un minuto

Tú: ¿Qué se discutió hoy en el espacio de lanzamiento?

Asistente: Lista los mensajes de hoy con remitentes e hilos. Nada cambia.

Tú: Responde en el hilo de despliegue que el lanzamiento está terminado.

Asistente: Muestra el espacio objetivo, el hilo y el texto redactado, luego pide confirmación antes de enviar.

Tú: Confirmar.

Asistente: Envía la respuesta bajo tu nombre en ese hilo. No toca ningún otro mensaje.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Cómo actúa el servidor en Chat
• Qué puede cambiar
• Obtener acceso
• Configuración
• Datos, límites y trabajo en segundo plano
• Documentación técnica
• Soporte

Inicio rápido

Necesitas Node.js 20+ y una cuenta de Google con acceso a Google Chat. No se requieren credenciales al momento de la instalación — el servidor se conecta desde la conversación.

1. Añade el servidor a tu aplicación de IA.
2. Di "conectar Google Chat": el asistente te guía a través de la creación del cliente OAuth y la aprobación del acceso sin editar archivos de configuración ni reiniciar.
3. Haz la pregunta de solo lectura anterior.

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"]
    }
  }
}

Qué puedes pedirle que haga

Ponerse al día en una conversación

• Muestra mis espacios y encuentra el mensaje directo con alex@example.com.
• ¿Qué se publicó hoy en el espacio de lanzamiento? Resume las decisiones.
• Muestra todo el hilo al que pertenece este mensaje.

Publicar y mantener mensajes

• Envía una actualización de estado al espacio del equipo.
• Responde en el hilo de despliegue que el lanzamiento está terminado.
• Corrige el error tipográfico en mi último mensaje, o elimínalo por completo.

Reaccionar y revisar archivos adjuntos

• Añade un 👍 al anuncio y muestra quién más reaccionó y con qué.
• Elimina mi reacción de ese mensaje.
• ¿Qué archivos están adjuntos a este mensaje? Muestra sus nombres y tipos.

Gestionar quién está en un espacio

• ¿Quién está en este espacio y quiénes son sus administradores?
• Añade a alex@example.com al espacio y hazlo administrador.
• Elimina a un excompañero del espacio.

Cómo actúa el servidor en Chat

1. Con las credenciales de actualización OAuth, el servidor actúa como el usuario con sesión iniciada: los mensajes se envían bajo tu nombre, y las ediciones y eliminaciones solo alcanzan tus propios mensajes y reacciones. Los cambios de membresía además requieren que seas administrador del espacio.
2. Los espacios aceptan un id simple, pero los mensajes, hilos, miembros, reacciones y archivos adjuntos se abordan por los nombres de recurso completos que devuelve la API — primero lista, luego actúa sobre un nombre exacto.
3. Una respuesta apunta a un hilo por su nombre o por una clave de hilo. Por defecto, un envío recurre a iniciar un nuevo hilo cuando el destino no puede ser enhebrado; puedes pedir que falle en su lugar.
4. Actuar como una aplicación de Chat — tarjetas, mensajes directos de aplicación, el endpoint dedicado de archivos adjuntos, eliminaciones forzadas — es una configuración separada de Google Cloud; el único puente aquí es un token de acceso de cuenta de servicio proporcionado como GOOGLE_CHAT_ACCESS_TOKEN.

La API de Chat no puede buscar texto de mensajes — los únicos filtros de mensajes son el tiempo de creación y el hilo. find_direct_message encuentra un DM existente pero nunca crea uno, y los bytes de archivos no se descargan ni se suben a través de este servidor. La creación de espacios y los otros métodos de API no cubiertos pasan por raw_request.

Qué puede cambiar

El cliente de IA controla los avisos de confirmación. El servidor marca las herramientas de lectura, escritura y destructivas para que el cliente pueda distinguir entre ponerse al día y publicar.

Obtener acceso

Google Chat requiere OAuth 2.0; una clave de API no es suficiente. Hay dos formas de entrar, y la primera no necesita archivos de configuración.

Conectarse desde el chat (recomendado)

Di "conectar Google Chat" y el asistente ejecuta el flujo contigo:

1. setup_instructions imprime la lista de verificación: crea o selecciona un proyecto de Google Cloud, habilita la API de Google Chat, configura la pantalla de consentimiento y crea un cliente OAuth de aplicación de escritorio.
2. Descarga el JSON de ese cliente ("Descargar JSON") y dale al asistente su ruta — set_client lo almacena solo para el propietario. El secreto nunca pasa por la conversación.
3. start_login devuelve un enlace de consentimiento de Google. Ábrelo en esta máquina y aprueba; el código vuelve a un listener de un solo uso en 127.0.0.1 (PKCE), nunca a través del chat.
4. finish_login intercambia el código, guarda los tokens en ~/.config/mcp-google-chat/credentials.json (modo 0600) y los verifica con una llamada real a la API de Chat — así, una API de Chat que aún está desactivada se detecta allí mismo, no en tu primera pregunta real.

Los tokens se releen en cada llamada, por lo que la conexión funciona de inmediato — sin reiniciar la aplicación de IA. auth_status muestra lo que está conectado, logout revoca y elimina. El inicio de sesión solicita chat.spaces.readonly, chat.messages, chat.messages.reactions y chat.memberships.readonly; el ámbito de administración detrás de search_spaces no se solicita — usa la ruta de entorno si lo necesitas.

Variables de entorno (CI, instalaciones desatendidas)

1. Crea o selecciona un proyecto de Google Cloud y habilita API de Google Chat.

2. Configura la pantalla de consentimiento OAuth y crea un cliente OAuth de aplicación de escritorio.

3. Autoriza la cuenta de Google con la que chateas. El Playground de OAuth 2.0 puede obtener el token de actualización cuando Usar tus propias credenciales OAuth está habilitado.

4. Solicita solo los ámbitos que tus sesiones necesitan. Para leer y enviar, esto es 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
   

   La tabla completa por tarea — editar y eliminar tus propios mensajes, reacciones, membresías, búsqueda de administración — está en docs/TOOLS.md.

Los tokens de actualización OAuth en modo de prueba pueden expirar después de siete días. Publica la aplicación OAuth, o usa una aplicación Interna en un dominio de Workspace, cuando necesites acceso de larga duración. Trata el secreto del cliente y el token de actualización como contraseñas.

Para una sesión rápida, un token de corta duración en GOOGLE_CHAT_ACCESS_TOKEN también funciona — por ejemplo de gcloud auth print-access-token con ámbitos de Chat concedidos. La misma variable es cómo un token de aplicación de Chat de cuenta de servicio llega al servidor cuando necesitas funciones solo de aplicación.

Configuración

Cada variable es opcional — sin ninguna de ellas, el servidor se conecta desde el chat.

* Para la ruta de entorno, proporciona el trío OAuth o un token de acceso. Cuando se establecen, tienen prioridad sobre un inicio de sesión en el chat almacenado y el servidor nunca los actualiza ni los elimina.

Iniciado sin credenciales, el servidor aún completa el protocolo de enlace MCP; las instrucciones y la primera llamada a una herramienta nombran ambas soluciones — el inicio de sesión en el chat (sin reinicio) y las variables de entorno (reinicio).

Datos, límites y trabajo en segundo plano

• Las solicitudes van a Google Chat. El servidor local actualiza los tokens OAuth de Google y llama a la API de Chat; el token nunca se envía a ningún otro host. Su telemetría anónima contiene un ID de instalación, versión del paquete, cliente de IA y versiones de plataforma, y nombres de herramientas — nunca tokens OAuth, contenido de mensajes, argumentos de herramientas o prompts. Establece ASKADS_TELEMETRY=0 para optar por no participar.
• Google aplica cuotas por proyecto y por usuario. En 429, el servidor usa backoff; las lecturas también se reintentan después de errores de red y 5xx, mientras que las escrituras nunca se reproducen después de una falla incierta — un envío reproducido sería un mensaje duplicado en una sala real. send_message acepta un ID de mensaje personalizado que hace que un envío sea direccionable y deduplicable.
• No hay sondeo en segundo plano. El servidor solo se ejecuta cuando se le llama. list_messages puede sondear un espacio de forma incremental por tiempo de creación si tu aplicación de IA admite tareas programadas; las suscripciones a eventos de espacio pasan por raw_request.

Documentación técnica

• Catálogo de capacidades de MCP — páginas orientadas a tareas para cada herramienta.
• Todas las herramientas y entradas
• Documentación de desarrollo
• Documentación de publicación
• Referencia de la API de Google Chat

Soporte

¿Encontraste un error o necesitas un escenario? Crea un issue o escribe en Telegram.

¡Llegaste al final!