mcp-google-contacts

Google Contacts MCP

Español | Русский

A1 Google Contacts MCP permite que una aplicación de IA gestione tu libreta de direcciones de Google en lenguaje natural. Busca un contacto, crea o actualiza uno, organiza contactos con etiquetas, ejecuta importaciones por lotes y limpiezas, y convierte los "Otros contactos" guardados automáticamente en contactos reales.

Utiliza la API de Google People (la API detrás de Google Contacts) con tu cuenta de Google. Protege cada actualización contra ediciones concurrentes, mantiene las lecturas compactas con máscaras de campo explícitas y hace explícitos los límites de la API de People en lugar de dar a entender que cualquier tarea de contactos es posible.

• 25 herramientas. Lista, busca y lee contactos, créalos, actualízalos y elimínalos uno a uno o en lotes, gestiona grupos de contactos y membresías, y accede a "Otros contactos".
• Se conecta desde la conversación. Di "conectar Google Contacts": 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.
• Las actualizaciones no sobrescriben. Cada actualización está protegida por etag: si un contacto cambió en otro lugar desde que se leyó, la escritura falla en lugar de sobrescribir silenciosamente la edición concurrente.
• Las eliminaciones son reales. La API de People no tiene papelera; eliminar un contacto o grupo es permanente, y el servidor marca esas herramientas como destructivas para que tu aplicación de IA pueda preguntar primero.
• Ámbitos de Google mínimos. Utiliza contacts para lectura/escritura — contacts.readonly es suficiente para una configuración de solo lectura — además de contacts.other.readonly solo para "Otros contactos", sin acceso amplio a la cuenta.

Comienza con una pregunta de solo lectura:

Encuentra a todos los de Acme en mis contactos y muestra sus correos electrónicos y números de teléfono.

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

Véalo funcionar en un minuto

Tú: Muestra mi tarjeta de contacto de Jane Doe — correo electrónico, teléfono y empresa.

Asistente: Encuentra el contacto y muestra los campos solicitados. Nada cambia.

Tú: Cambia su número de teléfono a +1 415 555 0100 y añádela a la etiqueta "Clientes".

Asistente: Muestra el contacto y el cambio propuesto, luego pide confirmación antes de escribir.

Tú: Confirmo.

Asistente: Aplica la actualización protegida por etag y la etiqueta. Si el contacto cambió en otro lugar mientras tanto, la escritura falla en lugar de sobrescribirlo.

Contenido

• Inicio rápido
• Qué puedes pedirle que haga
• Cómo cambia un contacto
• 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. 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 Contacts": 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.
3. Haz la pregunta de solo lectura anterior.

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

codex mcp list

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

claude mcp list

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

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

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

Qué puedes pedirle que haga

Encontrar e inspeccionar contactos

• Encuentra a todos los de Acme y muestra sus correos electrónicos y números de teléfono.
• Muestra quién está en la etiqueta "Clientes".
• Lista los contactos que cambiaron desde la última sincronización.

Mantener la libreta de direcciones actualizada

• Crea un contacto para Jane Doe con su correo electrónico, teléfono y empresa.
• Actualiza el número de teléfono o el cargo de un contacto.
• Importa cincuenta personas en un solo lote, o elimina contactos obsoletos en una sola llamada.

Organizar con etiquetas

• Crea una etiqueta "Clientes" y añade estos contactos a ella.
• Renombra una etiqueta, o mueve un contacto de una etiqueta a otra.
• Elimina una etiqueta sin eliminar sus contactos — o con ellos, pero solo cuando se pida explícitamente.

Trabajar con "Otros contactos"

• Muestra las direcciones que Google guardó automáticamente que no están en mis contactos.
• Copia uno de ellos en Mis contactos como contacto real.

Cómo cambia un contacto

1. Cada contacto, grupo y otro contacto tiene un nombre de recurso completo (people/c..., contactGroups/..., otherContacts/...); las herramientas se dirigen a los registros por él, exactamente como lo devuelve la API.
2. Las lecturas devuelven solo los campos nombrados en la máscara de campo (predeterminado: nombres, correos electrónicos, teléfonos, organizaciones, membresías de grupos). Un campo ausente puede simplemente estar fuera de la máscara, no vacío.
3. Una actualización reemplaza cada grupo de campos proporcionado en su totalidad y está protegida por un etag: si el contacto cambió en otro lugar desde que se leyó, la escritura falla en lugar de sobrescribir la edición concurrente.
4. Las eliminaciones son permanentes. La API de People no tiene papelera ni deshacer.

La búsqueda cubre una caché que puede retrasarse unos segundos respecto a escrituras recientes y devuelve como máximo 30 resultados. Los "Otros contactos" — direcciones que Google guarda automáticamente — solo se pueden leer o copiar en Mis contactos, no editar en su lugar. Las fotos de contacto no tienen una herramienta dedicada; raw_request accede a esos endpoints.

Qué puede cambiar

El cliente de IA controla los avisos de confirmación. El servidor marca las lecturas, escrituras y herramientas destructivas para que el cliente pueda distinguir una inspección de un cambio en vivo.

Obtener acceso

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

Conectar desde el chat (recomendado)

Di "conectar Google Contacts" 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 Google People API, 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 y guarda los tokens en ~/.config/mcp-google-contacts/credentials.json (modo 0600) y los verifica con una llamada real a la API de Google People — así, una API que aún está desactivada se detecta allí mismo.

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.

Variables de entorno (CI, instalaciones desatendidas)

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

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

3. Autoriza la cuenta de Google cuyos contactos quieres gestionar. El OAuth 2.0 Playground puede obtener el token de actualización cuando Usar tus propias credenciales OAuth está habilitado.

4. Solicita los ámbitos mínimos para lo que uses:

   https://www.googleapis.com/auth/contacts
   https://www.googleapis.com/auth/contacts.other.readonly
   

contacts cubre la lectura y escritura de contactos y grupos; para una configuración de solo lectura contacts.readonly solo es suficiente. contacts.other.readonly se necesita solo para las herramientas de "Otros contactos". Un 403 en una sola herramienta generalmente significa que el token de actualización se creó sin el ámbito que esa herramienta necesita — vuelve a dar consentimiento con el ámbito faltante añadido.

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.

Configuración

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

* Proporciona el trío OAuth o un token de acceso. Sin credenciales en absoluto, el servidor aún se inicia y completa el protocolo de enlace MCP; la primera llamada a una herramienta entonces nombra las variables exactas a configurar.

Datos, límites y trabajo en segundo plano

• Las solicitudes van a Google. El servidor local actualiza los tokens OAuth de Google y llama a la API de People en people.googleapis.com. 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, datos de contactos, argumentos de herramientas o indicaciones. Establece ASKADS_TELEMETRY=0 para optar por no participar.
• Las cuotas de Google son por usuario y bajas. La cuota predeterminada de la API de People permite aproximadamente 90 lecturas y 90 escrituras por usuario por minuto, por lo que las herramientas por lotes superan a los bucles de llamadas individuales; los lotes de mutación deben ejecutarse uno a la vez. En 429 el servidor retrocede y reintenta; las lecturas también reintentan después de errores de red y 5xx, mientras que las escrituras no se reproducen después de una falla incierta.
• No hay sondeo en segundo plano. El servidor solo se ejecuta cuando se le llama. list_contacts admite tokens de sincronización, por lo que una aplicación de IA con tareas programadas puede obtener periódicamente solo lo que cambió; un token de sincronización caduca después de aproximadamente siete días, tras lo cual se necesita una nueva lista completa.

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 People de Google

Soporte

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

¡Llegaste al final!