MCP Google Contacts Server
Provides comprehensive Google Contacts management including creating, reading, updating, and deleting contacts with 25+ fields, advanced multi-field search, contact groups/labels management, and Google Workspace directory integration.
Integrates with Google Cloud's People API to enable contact management operations, requiring OAuth 2.0 credentials and API enablement through Google Cloud Console.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP Google Contacts Server search for contacts with 'engineer' in their job title"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📇 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
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.txtSet up Google API credentials (choose one):
Option A: Credentials file
Download
credentials.jsonfrom Google Cloud ConsolePlace 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.pyCommand Line Options
--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
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 paginationsearch_contacts- Advanced multi-field searchget_contact- Get detailed contact informationcreate_contact- Create contact with basic fields (11 fields)create_contact_advanced- Create contact with all fields (25+ fields)update_contact- Update contact with basic fieldsupdate_contact_advanced- Update contact with all fieldsdelete_contact- Delete a contact
Contact Groups (Labels)
list_contact_groups- List all contact groups/labelscreate_contact_group- Create new contact groupget_contact_group- Get group details and membersupdate_contact_group- Update group namedelete_contact_group- Delete user-created groupsadd_contacts_to_group- Add contacts to a groupremove_contacts_from_group- Remove contacts from groupsearch_contacts_by_group- Find contacts in specific group
Google Workspace
list_workspace_users- List organization directorysearch_directory- Search workspace directoryget_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:
contactsanddirectory.readonly
Search Not Working
Use server-side search with
search_contactsTry different search terms or fields
Performance Issues
Use pagination with
max_resultsparameterSet
include_all_fields=Falsefor 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 toolsadd_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
Scored across 19 tools
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.
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.
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.
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
Related MCP Connectors
Keeps your contacts in sync across Google, Microsoft, Apple and CardDAV, and cleans up duplicates.
Read and update Pobuca Connect contacts and organizations; look up teams and custom fields.
Read and write Less Annoying CRM contacts, notes, tasks, events, pipelines and groups.
Permissioned access to Gmail, Drive and Calendar via the user's own Google account
Related MCP Servers
- AlicenseAqualityDmaintenanceA 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.933MIT
- AlicenseNot gradedqualityDmaintenanceEnables 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.2Creative Commons Attribution Non Commercial Share Alike 4.0 International
- AlicenseNot gradedqualityDmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityDmaintenanceGives AI assistants access to Google Contacts, supporting listing, searching, creating, updating, and deleting contacts, as well as searching Google Workspace directories.MIT