Skip to main content
Glama
MCP Google Contacts Server

MCP Google Contacts Server

by 4tal

📇 MCP Google Contacts Server

A Machine Conversation Protocol (MCP) server that provides comprehensive Google Contacts functionality for AI assistants.

✨ Features

  • Complete Contact Management: Create, read, update, and delete contacts with 25+ fields

  • Advanced Search: Multi-field search across names, emails, phones, and organizations

  • Contact Groups: Full label/group management and organization

  • Google Workspace Integration: Directory search and user management

  • Efficient Performance: Pagination support for large contact lists (1000+ contacts)

  • Rich Field Support: Multiple emails/phones, addresses, birthdays, relationships, custom fields

Related MCP server: Google Contacts MCP Server

🚀 Installation

Prerequisites

  • Python 3.12 or higher

  • Google account with contacts access

  • Google Cloud project with People API enabled

  • OAuth 2.0 credentials

Setup

  1. Clone and install:

    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. Set up Google API credentials (choose one):

    Option A: Credentials file

    • Download credentials.json from Google Cloud Console

    • Place in project root or specify with --credentials-file

    Option B: Environment variables

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

🛠️ Usage

Basic Startup

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

Command Line Options

  • --transport: Protocol (stdio or http, default: stdio)

  • --host: HTTP host (default: localhost)

  • --port: HTTP port (default: 8000)

  • --credentials-file: Path to credentials.json

  • --client-id, --client-secret, --refresh-token: OAuth credentials

Examples

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

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

🔌 MCP Client Integration

Add to your MCP configuration:

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

🧰 Available Tools

Contact Management

  • list_contacts - List all contacts with filtering and pagination

  • search_contacts - Advanced multi-field search

  • get_contact - Get detailed contact information

  • create_contact - Create contact with basic fields (11 fields)

  • create_contact_advanced - Create contact with all fields (25+ fields)

  • update_contact - Update contact with basic fields

  • update_contact_advanced - Update contact with all fields

  • delete_contact - Delete a contact

Contact Groups (Labels)

  • list_contact_groups - List all contact groups/labels

  • create_contact_group - Create new contact group

  • get_contact_group - Get group details and members

  • update_contact_group - Update group name

  • delete_contact_group - Delete user-created groups

  • add_contacts_to_group - Add contacts to a group

  • remove_contacts_from_group - Remove contacts from group

  • search_contacts_by_group - Find contacts in specific group

Google Workspace

  • list_workspace_users - List organization directory

  • search_directory - Search workspace directory

  • get_other_contacts - Get "other contacts"

📝 Quick Examples

Search Contacts

# Basic search
search_contacts("john smith")

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

# Search phone numbers
search_contacts("+1234567890")

Create Contact

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

Manage Contact Groups

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

❓ Troubleshooting

Authentication Issues

  • Ensure People API is enabled in Google Cloud Console

  • Check OAuth credentials are valid and have proper scopes

  • Required scopes: contacts and directory.readonly

Search Not Working

  • Use server-side search with search_contacts

  • Try different search terms or fields

Performance Issues

  • Use pagination with max_results parameter

  • Set include_all_fields=False for faster queries

🔧 Development

# Development setup
uv sync --dev

# Format code
./scripts/format.sh

# Run linting
./scripts/lint.sh

# Test
uv run python test_contact_groups.py

📄 License

MIT License - see LICENSE file for details.


Note: This server provides comprehensive Google Contacts functionality with support for all contact fields, advanced search, contact groups, and efficient handling of large contact lists.

Available Tools

19 tools
add_contacts_to_groupA

Add contacts to a contact group (assign a label to contacts).

    Args:
        group_resource_name: Contact group resource name (e.g., "contactGroups/12345")
        contact_resource_names: List of contact resource names to add (e.g., ["people/12345", "people/67890"])
    

Inputs: group_resource_name (required), contact_resource_names (required).

create_contactB

Create a new contact with comprehensive field support.

    Args:
        given_name: First name of the contact
        family_name: Last name of the contact
        email: Email address of the contact
        phone: Phone number of the contact
        organization: Company/organization name
        job_title: Job title or position
        address: Physical address
        birthday: Birthday in YYYY-MM-DD format
        website: Website URL
        notes: Notes or biography
        nickname: Nickname
    

Inputs: given_name (required), family_name, email, phone, +7 more.

create_contact_advancedB

Create a new contact with full field support including multiple emails, phones, addresses, etc.

    Args:
        contact_data: Dictionary containing complete contact information with support for:
            - Multiple emails: {"emails": [{"value": "email@example.com", "type": "work"}]}
            - Multiple phones: {"phones": [{"value": "+1234567890", "type": "mobile"}]}
            - Multiple addresses: {"addresses": [{"formatted": "123 Main St", "type": "home"}]}
            - Relations: {"relations": [{"person": "John Doe", "type": "spouse"}]}
            - Events: {"events": [{"date": {"month": 12, "day": 25}, "type": "anniversary"}]}
            - Custom fields: {"custom_fields": [{"key": "Department", "value": "Engineering"}]}
    

Inputs: contact_data (required).

create_contact_groupB

Create a new contact group (label) to organize your contacts.

    Args:
        name: Name for the new contact group (e.g., "Work Colleagues", "Family", "Book Club")
        client_data: Optional custom data as list of key-value pairs (e.g., [{"key": "color", "value": "blue"}])
    

Inputs: name (required), client_data.

delete_contactB

Delete a contact by resource name.

    Args:
        resource_name: Contact resource name (people/*) to delete
    

Inputs: resource_name (required).

delete_contact_groupA

Delete a contact group. Note: This only works for user-created groups, not system groups.

    Args:
        resource_name: Contact group resource name (e.g., "contactGroups/12345")
    

Inputs: resource_name (required).

get_contactB

Get a contact by resource name or email with comprehensive information.

    Args:
        identifier: Resource name (people/*) or email address of the contact
        include_all_fields: Whether to include all contact fields (default: True)
    

Inputs: identifier (required), include_all_fields.

get_contact_groupB

Get detailed information about a specific contact group.

    Args:
        resource_name: Contact group resource name (e.g., "contactGroups/12345")
        include_members: Whether to include the list of member contact IDs
        max_members: Maximum number of member IDs to return if include_members is True
    

Inputs: resource_name (required), include_members, max_members.

get_other_contactsB

Retrieve contacts from the 'Other contacts' section.

    Other contacts are people you've interacted with but haven't added to your contacts list.
    These often include email correspondents that aren't in your main contacts.

    Args:
        max_results: Maximum number of results to return (default: 50)
    

Inputs: max_results.

list_contact_groupsB

List all contact groups (labels) in your Google Contacts.

    Contact groups are like labels that help you organize your contacts into categories
    such as 'Family', 'Work', 'Friends', etc.

    Args:
        include_system_groups: Whether to include system groups like "My Contacts", "Starred", etc.
    

Inputs: include_system_groups.

list_contactsB

List all contacts or filter by name with comprehensive field support.

    Args:
        name_filter: Optional filter to find contacts by name
        max_results: Maximum number of results to return (default: 100)
        include_all_fields: Whether to include all contact fields like addresses, birthdays, etc.
    

Inputs: name_filter, max_results, include_all_fields.

list_workspace_usersB

List Google Workspace users in your organization's directory.

    This tool allows you to search and list users in your Google Workspace directory,
    including their email addresses and other information.

    Args:
        query: Optional search term to find specific users (name, email, etc.)
        max_results: Maximum number of results to return (default: 50)
    

Inputs: query, max_results.

remove_contacts_from_groupA

Remove contacts from a contact group (remove a label from contacts).

    Args:
        group_resource_name: Contact group resource name (e.g., "contactGroups/12345")
        contact_resource_names: List of contact resource names to remove (e.g., ["people/12345", "people/67890"])
    

Inputs: group_resource_name (required), contact_resource_names (required).

search_contactsB

Enhanced search contacts by name, email, phone, organization, or other fields.

    This uses server-side search when available and falls back to comprehensive client-side search.

    Args:
        query: Search term to find in contacts
        max_results: Maximum number of results to return (default: 50)
        search_fields: Specific fields to search in (e.g., ['emails', 'phones', 'organization'])
    

Inputs: query (required), max_results, search_fields.

search_contacts_by_groupA

Find all contacts that belong to a specific contact group.

    This is useful for seeing which contacts have a particular label assigned.

    Args:
        group_resource_name: Contact group resource name (e.g., "contactGroups/12345")
        max_results: Maximum number of contacts to return
    

Inputs: group_resource_name (required), max_results.

search_directoryC

Search for people specifically in the Google Workspace directory.

    This performs a more targeted search of your organization's directory.

    Args:
        query: Search term to find specific directory members
        max_results: Maximum number of results to return (default: 20)
    

Inputs: query (required), max_results.

update_contactB

Update an existing contact with comprehensive field support.

    Args:
        resource_name: Contact resource name (people/*)
        given_name: Updated first name
        family_name: Updated last name
        email: Updated email address
        phone: Updated phone number
        organization: Updated company/organization name
        job_title: Updated job title or position
        address: Updated physical address
        birthday: Updated birthday in YYYY-MM-DD format
        website: Updated website URL
        notes: Updated notes or biography
        nickname: Updated nickname
    

Inputs: resource_name (required), given_name, family_name, email, +8 more.

update_contact_advancedC

Update an existing contact with full field support including multiple emails, phones, addresses, etc.

    Args:
        resource_name: Contact resource name (people/*)
        contact_data: Dictionary containing updated contact information with full field support
    

Inputs: resource_name (required), contact_data (required).

update_contact_groupB

Update a contact group's name and custom data.

    Args:
        resource_name: Contact group resource name (e.g., "contactGroups/12345")
        name: New name for the contact group
        client_data: Optional updated custom data as list of key-value pairs
    

Inputs: resource_name (required), name (required), client_data.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 19 tools

    Disambiguation3/5

    Most tools have distinct purposes, but there is notable overlap between create_contact and create_contact_advanced, and between update_contact and update_contact_advanced, which could confuse agents about which to use. Additionally, search_contacts and search_contacts_by_group have overlapping search functionality, though their descriptions help differentiate them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case, such as create_contact, delete_contact_group, and list_contacts. This predictability makes the tool set easy to navigate and understand at a glance.

    Tool Count4/5

    With 19 tools, the count is slightly high but reasonable for a Google Contacts server, covering contacts, groups, and directory operations. It includes essential CRUD and search functions, though some redundancy (like advanced vs. basic create/update) contributes to the higher number.

    Completeness5/5

    The tool set provides comprehensive coverage for managing Google Contacts, including full CRUD for contacts and groups, search across multiple dimensions, and integration with Google Workspace. There are no obvious gaps; agents can perform all typical contact management workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Machine Conversation Protocol server that enables AI assistants to manage Google Contacts and search Google Workspace directories, providing tools for listing, creating, updating, and deleting contacts within your Google account.
      9
      33
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to access and search Google Contacts through per-user OAuth authentication on serverless AWS Lambda. Provides read-only access to personal contacts with zero data storage and real-time API queries.
      2
      Creative Commons Attribution Non Commercial Share Alike 4.0 International
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables comprehensive management of Google Calendar, Contacts, and Gmail through AI systems. Supports full CRUD operations including creating/updating/deleting events, managing contacts, sending emails, organizing with labels, and batch operations with OAuth2 authentication.
      101 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Gives AI assistants access to Google Contacts, supporting listing, searching, creating, updating, and deleting contacts, as well as searching Google Workspace directories.
      MIT