MCP Google Contacts Server

Servidor de contactos de Google MCP

Un servidor de Protocolo de conversación de máquina (MCP) que proporciona la funcionalidad de Contactos de Google, lo que permite a los asistentes de IA administrar contactos, buscar en el directorio de su organización e interactuar con Google Workspace.

✨ Características

• Listado y búsqueda de contactos de Google
• Crear, actualizar y eliminar contactos
• Buscar en el directorio de Google Workspace
• Ver "Otros contactos" (personas con las que has interactuado pero que no has agregado)
• Acceda a los usuarios de Google Workspace en su organización

🚀 Instalación

📋 Requisitos previos

• Python 3.12 o superior
• Cuenta de Google con acceso a contactos
• Proyecto de Google Cloud con People API habilitada
• Credenciales OAuth 2.0 para el acceso a la API de Google

🧪 Uso de uv (Recomendado)

1. Instala uv si aún no lo tienes:
   pip install uv
2. Clonar el repositorio:
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
3. Cree un entorno virtual e instale dependencias:
   uv venv source .venv/bin/activate uv pip install -r requirements.txt

📦 Usando pip

1. Clonar el repositorio:
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
2. Instalar dependencias:
   pip install -r requirements.txt

🔑 Configuración de autenticación

El servidor requiere las credenciales de la API de Google para acceder a tus contactos. Tienes varias opciones:

🔐 Opción 1: Usar un archivo credentials.json

1. Cree un proyecto de Google Cloud y habilite la API People
2. Crear credenciales OAuth 2.0 (tipo de aplicación de escritorio)
3. Descargue el archivo credentials.json
4. Colóquelo en uno de estos lugares:
   • El directorio raíz de este proyecto
   • Su directorio de inicio (~/google-contacts-credentials.json)
   • Especifique su ubicación con el argumento --credentials-file

🔐 Opción 2: Uso de variables de entorno

Establezca las siguientes variables de entorno:

• GOOGLE_CLIENT_ID : Su ID de cliente de Google OAuth
• GOOGLE_CLIENT_SECRET : Su secreto de cliente de Google OAuth
• GOOGLE_REFRESH_TOKEN : Un token de actualización válido para su cuenta

🛠️ Uso

🏃‍♂️ Inicio básico

Esto inicia el servidor con el transporte stdio predeterminado.

⚙️ Argumentos de la línea de comandos

📝 Ejemplos

Comience con el transporte HTTP:

Utilice un archivo de credenciales específico:

Proporcione las credenciales directamente:

🔌 Integración con clientes MCP

Para utilizar este servidor con clientes MCP (como Claude de Anthropic con Cline), agréguelo a su configuración de MCP:

🧰 Herramientas disponibles

Este servidor MCP proporciona las siguientes herramientas:

🔍 Descripciones detalladas de herramientas

📋 list_contacts

Enumera todos tus contactos de Google o los filtra por nombre.

Parámetros:

• name_filter (opcional): cadena para filtrar contactos por nombre
• max_results (opcional): Número máximo de contactos a devolver (predeterminado: 100)

Ejemplo:

👤 get_contact

Recupera información detallada sobre un contacto específico.

Parámetros:

• identifier : Nombre del recurso (personas/*) o dirección de correo electrónico del contacto

Ejemplo:

➕ create_contact

Crea un nuevo contacto en tus Contactos de Google.

Parámetros:

• given_name : Nombre del contacto
• family_name (opcional): Apellido del contacto
• email (opcional): Dirección de correo electrónico del contacto
• phone (opcional): Número de teléfono del contacto

Ejemplo:

✏️ update_contact

Actualiza un contacto existente con nueva información.

Parámetros:

• resource_name : Nombre del recurso de contacto (personas/*)
• given_name (opcional): Nombre actualizado
• family_name (opcional): Apellido actualizado
• email (opcional): Dirección de correo electrónico actualizada
• phone (opcional): Número de teléfono actualizado

Ejemplo:

🗑️ delete_contact

Elimina un contacto de tus Contactos de Google.

Parámetros:

• resource_name : Nombre del recurso de contacto (personas/*) para eliminar

Ejemplo:

🔍 search_contacts

Busca tus contactos por nombre, correo electrónico o número de teléfono.

Parámetros:

• query : Término de búsqueda para encontrar en contactos
• max_results (opcional): Número máximo de resultados a devolver (predeterminado: 10)

Ejemplo:

🏢 list_workspace_users

Enumera los usuarios de Google Workspace en el directorio de tu organización.

Parámetros:

• query (opcional): término de búsqueda para encontrar usuarios específicos
• max_results (opcional): Número máximo de resultados a devolver (predeterminado: 50)

Ejemplo:

🔭 search_directory

Realiza una búsqueda específica en el directorio de Google Workspace de su organización.

Parámetros:

• query : término de búsqueda para encontrar miembros específicos del directorio
• max_results (opcional): Número máximo de resultados a devolver (predeterminado: 20)

Ejemplo:

👥 get_other_contacts

Recupera contactos de la sección “Otros contactos”: personas con las que has interactuado pero que no has agregado a tus contactos.

Parámetros:

• max_results (opcional): Número máximo de resultados a devolver (predeterminado: 50)

Ejemplo:

🔒 Permisos

Al ejecutar el servidor por primera vez, deberá autenticarse con Google y otorgar los permisos necesarios para acceder a sus contactos. El proceso de autenticación le guiará.

❓ Solución de problemas

• 🔐 Problemas de autenticación : asegúrese de que sus credenciales sean válidas y tengan los alcances necesarios
• ⚠️ Límites de API : tenga en cuenta los límites de cuota de la API de Google People
• 📝 Registros : Verifique la salida de la consola en busca de mensajes de error e información de depuración

👥 Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

📄 Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.