Google Contacts

Gestiona tus contactos de Google, permitiéndote crear, buscar y actualizar contactos.

GitHub
1
Prueba este MCPPatrocinado

Documentación

📇 Servidor MCP de Google Contacts

Un servidor de Protocolo de Conversación entre Máquinas (MCP) que proporciona funcionalidad completa de Google Contacts para asistentes de IA.

✨ Características

  • Gestión completa de contactos: Crear, leer, actualizar y eliminar contactos con más de 25 campos
  • Búsqueda avanzada: Búsqueda en múltiples campos entre nombres, correos electrónicos, teléfonos y organizaciones
  • Grupos de contactos: Gestión completa de etiquetas/grupos y organización
  • Integración con Google Workspace: Búsqueda en el directorio y gestión de usuarios
  • Rendimiento eficiente: Soporte de paginación para listas grandes de contactos (más de 1000 contactos)
  • Soporte de campos enriquecidos: Múltiples correos/teléfonos, direcciones, cumpleaños, relaciones, campos personalizados

🚀 Instalación

Requisitos previos

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

Configuración

  1. Clonar e instalar:

    git clone git@github.com:4tal/mcp-google-contacts-server.git
cd mcp-google-contacts-server

# Using uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt

# Or using pip
pip install -r requirements.txt

  2. Configurar las credenciales de la API de Google (elige una opción):

    Opción A: Archivo de credenciales

    • Descargar credentials.json desde la consola de Google Cloud
    • Colocarlo en la raíz del proyecto o especificarlo con --credentials-file

    Opción B: Variables de entorno

    export GOOGLE_CLIENT_ID="your_client_id"
export GOOGLE_CLIENT_SECRET="your_client_secret"
export GOOGLE_REFRESH_TOKEN="your_refresh_token"

🛠️ Uso

Inicio básico

python src/main.py
# or
uv run src/main.py

Opciones de línea de comandos

  • --transport: Protocolo (stdio o http, por defecto: stdio)
  • --host: Host HTTP (por defecto: localhost)
  • --port: Puerto HTTP (por defecto: 8000)
  • --credentials-file: Ruta al archivo credentials.json
  • --client-id, --client-secret, --refresh-token: Credenciales OAuth

Ejemplos

# HTTP transport
python src/main.py --transport http --port 8080

# Specific credentials file
python src/main.py --credentials-file /path/to/credentials.json

🔌 Integración con clientes MCP

Añade a tu configuración de MCP:

{
  "mcpServers": {
    "google-contacts-server": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/mcp-google-contacts-server",
        "run", "main.py"
      ]
    }
  }
}

🧰 Herramientas disponibles

Gestión de contactos

  • list_contacts - Listar todos los contactos con filtrado y paginación
  • search_contacts - Búsqueda avanzada en múltiples campos
  • get_contact - Obtener información detallada de un contacto
  • create_contact - Crear contacto con campos básicos (11 campos)
  • create_contact_advanced - Crear contacto con todos los campos (más de 25 campos)
  • update_contact - Actualizar contacto con campos básicos
  • update_contact_advanced - Actualizar contacto con todos los campos
  • delete_contact - Eliminar un contacto

Grupos de contactos (Etiquetas)

  • list_contact_groups - Listar todos los grupos/etiquetas de contactos
  • create_contact_group - Crear un nuevo grupo de contactos
  • get_contact_group - Obtener detalles del grupo y sus miembros
  • update_contact_group - Actualizar el nombre del grupo
  • delete_contact_group - Eliminar grupos creados por el usuario
  • add_contacts_to_group - Añadir contactos a un grupo
  • remove_contacts_from_group - Eliminar contactos de un grupo
  • search_contacts_by_group - Encontrar contactos en un grupo específico

Google Workspace

  • list_workspace_users - Listar el directorio de la organización
  • search_directory - Buscar en el directorio de Workspace
  • get_other_contacts - Obtener "otros contactos"

📝 Ejemplos rápidos

Buscar contactos

# Basic search
search_contacts("john smith")

# Search specific fields
search_contacts("engineer", search_fields=["jobTitle", "organization"])

# Search phone numbers
search_contacts("+1234567890")

Crear contacto

# Basic contact
create_contact(
    given_name="John",
    family_name="Smith",
    email="john@example.com",
    phone="+1-555-123-4567",
    organization="Acme Corp",
    job_title="Software Engineer"
)

# Advanced contact with multiple fields
create_contact_advanced({
    "given_name": "Jane",
    "family_name": "Doe",
    "emails": [
        {"value": "jane@work.com", "type": "work"},
        {"value": "jane@personal.com", "type": "home"}
    ],
    "phones": [
        {"value": "+1-555-111-2222", "type": "mobile"}
    ],
    "organization": "Tech Corp",
    "birthday": "1985-03-22"
})

Gestionar grupos de contactos

# Create group
create_contact_group("Work Team")

# Add contacts to group
add_contacts_to_group("contactGroups/12345", ["people/67890", "people/11111"])

# Find contacts in group
search_contacts_by_group("contactGroups/12345")

❓ Solución de problemas

Problemas de autenticación

  • Asegúrate de que la API de People esté habilitada en la consola de Google Cloud
  • Verifica que las credenciales OAuth sean válidas y tengan los alcances adecuados
  • Alcances requeridos: contacts y directory.readonly

La búsqueda no funciona

  • Usa la búsqueda del lado del servidor con search_contacts
  • Prueba con diferentes términos o campos de búsqueda

Problemas de rendimiento

  • Usa paginación con el parámetro max_results
  • Establece include_all_fields=False para consultas más rápidas

🔧 Desarrollo

# Development setup
uv sync --dev

# Format code
./scripts/format.sh

# Run linting
./scripts/lint.sh

# Test
uv run python test_contact_groups.py

📄 Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Nota: Este servidor proporciona funcionalidad completa de Google Contacts con soporte para todos los campos de contacto, búsqueda avanzada, grupos de contactos y manejo eficiente de listas grandes de contactos.