Google Contacts

Gerencie seus Contatos do Google, permitindo criar, pesquisar e atualizar contatos.

GitHub
1
Experimente este MCPPatrocinado

Documentação

📇 Servidor MCP do Google Contacts

Um servidor de Protocolo de Conversação entre Máquinas (MCP) que fornece funcionalidades abrangentes do Google Contacts para assistentes de IA.

✨ Recursos

  • Gerenciamento Completo de Contatos: Crie, leia, atualize e exclua contatos com mais de 25 campos
  • Busca Avançada: Busca em múltiplos campos por nomes, e-mails, telefones e organizações
  • Grupos de Contatos: Gerenciamento completo de rótulos/grupos e organização
  • Integração com Google Workspace: Busca no diretório e gerenciamento de usuários
  • Desempenho Eficiente: Suporte a paginação para listas grandes de contatos (mais de 1000 contatos)
  • Suporte a Campos Ricos: Múltiplos e-mails/telefones, endereços, aniversários, relacionamentos, campos personalizados

🚀 Instalação

Pré-requisitos

  • Python 3.12 ou superior
  • Conta Google com acesso a contatos
  • Projeto no Google Cloud com a API People habilitada
  • Credenciais OAuth 2.0

Configuração

  1. Clone e instale:

    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. Configure as credenciais da API do Google (escolha uma opção):

    Opção A: Arquivo de credenciais

    • Baixe credentials.json do Console do Google Cloud
    • Coloque na raiz do projeto ou especifique com --credentials-file

    Opção B: Variáveis de ambiente

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

🛠️ Uso

Inicialização Básica

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

Opções de Linha de Comando

  • --transport: Protocolo (stdio ou http, padrão: stdio)
  • --host: Host HTTP (padrão: localhost)
  • --port: Porta HTTP (padrão: 8000)
  • --credentials-file: Caminho para credentials.json
  • --client-id, --client-secret, --refresh-token: Credenciais OAuth

Exemplos

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

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

🔌 Integração com Cliente MCP

Adicione à sua configuração MCP:

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

🧰 Ferramentas Disponíveis

Gerenciamento de Contatos

  • list_contacts - Lista todos os contatos com filtragem e paginação
  • search_contacts - Busca avançada em múltiplos campos
  • get_contact - Obtém informações detalhadas do contato
  • create_contact - Cria contato com campos básicos (11 campos)
  • create_contact_advanced - Cria contato com todos os campos (mais de 25 campos)
  • update_contact - Atualiza contato com campos básicos
  • update_contact_advanced - Atualiza contato com todos os campos
  • delete_contact - Exclui um contato

Grupos de Contatos (Rótulos)

  • list_contact_groups - Lista todos os grupos/rótulos de contatos
  • create_contact_group - Cria novo grupo de contatos
  • get_contact_group - Obtém detalhes do grupo e membros
  • update_contact_group - Atualiza nome do grupo
  • delete_contact_group - Exclui grupos criados pelo usuário
  • add_contacts_to_group - Adiciona contatos a um grupo
  • remove_contacts_from_group - Remove contatos de um grupo
  • search_contacts_by_group - Encontra contatos em grupo específico

Google Workspace

  • list_workspace_users - Lista diretório da organização
  • search_directory - Busca no diretório do workspace
  • get_other_contacts - Obtém "outros contatos"

📝 Exemplos Rápidos

Buscar Contatos

# Basic search
search_contacts("john smith")

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

# Search phone numbers
search_contacts("+1234567890")

Criar Contato

# 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"
})

Gerenciar Grupos de Contatos

# 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")

❓ Solução de Problemas

Problemas de Autenticação

  • Certifique-se de que a API People está habilitada no Console do Google Cloud
  • Verifique se as credenciais OAuth são válidas e possuem os escopos adequados
  • Escopos necessários: contacts e directory.readonly

Busca Não Funcionando

  • Use busca no lado do servidor com search_contacts
  • Tente diferentes termos ou campos de busca

Problemas de Desempenho

  • Use paginação com o parâmetro max_results
  • Defina include_all_fields=False para consultas mais rápidas

🔧 Desenvolvimento

# Development setup
uv sync --dev

# Format code
./scripts/format.sh

# Run linting
./scripts/lint.sh

# Test
uv run python test_contact_groups.py

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Nota: Este servidor fornece funcionalidades abrangentes do Google Contacts com suporte para todos os campos de contato, busca avançada, grupos de contatos e gerenciamento eficiente de grandes listas de contatos.