📇 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

🚀 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

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

🔌 MCP Client Integration

Add to your MCP configuration:

🧰 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

Create Contact

Manage Contact Groups

❓ 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

📄 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.