Google Contacts

Manage your Google Contacts, allowing you to create, search, and update contacts.

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

- 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

- Python 3.12 or higher
- Google account with contacts access
- Google Cloud project with People API enabled
- OAuth 2.0 credentials

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

Set up Google API credentials(choose one):

- Downloadcredentials.jsonfrom Google Cloud Console
- Place in project root or specify with--credentials-file

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

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

- --transport: Protocol (stdioorhttp, 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

# HTTP transport python src/main.py --transport http --port 8080 # Specific credentials file python src/main.py --credentials-file /path/to/credentials.json

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

- 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

- 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

- list_workspace_users- List organization directory
- search_directory- Search workspace directory
- get_other_contacts- Get "other contacts"

# Basic search search_contacts("john smith") # Search specific fields search_contacts("engineer", search_fields=["jobTitle", "organization"]) # Search phone numbers search_contacts("+1234567890")

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

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

- Ensure People API is enabled in Google Cloud Console
- Check OAuth credentials are valid and have proper scopes
- Required scopes:contactsanddirectory.readonly

- Use server-side search withsearch_contacts
- Try different search terms or fields

- Use pagination withmax_resultsparameter
- Setinclude_all_fields=Falsefor faster queries

# Development setup uv sync --dev # Format code ./scripts/format.sh # Run linting ./scripts/lint.sh # Test uv run python test_contact_groups.py

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.

A read-only MCP server for Google Contacts, powered by the CData JDBC Driver.

Hosted, Stateless & Multitenant Google People MCP server enables AI assistants to access, manage, and organize contacts and profile information through Google People API.

Official Dadan MCP server for AI access to videos, transcripts, analytics, and capture leads.

Centralized management of RePricing for Amazon, eBay, and Kaufland, Lost & Found for Amazon FBA, and integrated HelpDesk.

Contract and template management for drafting, reviewing, and sending binding contracts.

Find buyers and book more meetings without your AI Assistant

Qasper gives AI agents the tools to discover local service businesses, check availability, and book appointments in real time.

Find buying signals for companies and contacts

Query contacts, companies, and relationship data extracted from your email and calendar. Build pre-meeting reports, find warm intros, and identify fading relationships.

Tomba, your unique B2B email finder and verifier, provides a distinctive lead database for effortless and effective outreach scaling.