📇 MCP Google Contacts Server

A Machine Conversation Protocol (MCP) server that provides Google Contacts functionality, allowing AI assistants to manage contacts, search your organization's directory, and interact with Google Workspace.

✨ Features

• List and search Google Contacts
• Create, update, and delete contacts
• Search Google Workspace directory
• View "Other Contacts" (people you've interacted with but haven't added)
• Access Google Workspace users in your organization

🚀 Installation

📋 Prerequisites

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

🧪 Using uv (Recommended)

1. Install uv if you don't have it already:
   pip install uv
2. Clone the repository:
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
3. Create a virtual environment and install dependencies:
   uv venv source .venv/bin/activate uv pip install -r requirements.txt

📦 Using pip

1. Clone the repository:
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
2. Install dependencies:
   pip install -r requirements.txt

🔑 Authentication Setup

The server requires Google API credentials to access your contacts. You have several options:

🔐 Option 1: Using a credentials.json file

1. Create a Google Cloud project and enable the People API
2. Create OAuth 2.0 credentials (Desktop application type)
3. Download the credentials.json file
4. Place it in one of these locations:
   • The root directory of this project
   • Your home directory (~/google-contacts-credentials.json)
   • Specify its location with the --credentials-file argument

🔐 Option 2: Using environment variables

Set the following environment variables:

• GOOGLE_CLIENT_ID: Your Google OAuth client ID
• GOOGLE_CLIENT_SECRET: Your Google OAuth client secret
• GOOGLE_REFRESH_TOKEN: A valid refresh token for your account

🛠️ Usage

🏃‍♂️ Basic Startup

This starts the server with the default stdio transport.

⚙️ Command Line Arguments

📝 Examples

Start with HTTP transport:

Use specific credentials file:

Provide credentials directly:

🔌 Integration with MCP Clients

To use this server with MCP clients (like Anthropic's Claude with Cline), add it to your MCP configuration:

🧰 Available Tools

This MCP server provides the following tools:

🔍 Detailed Tool Descriptions

📋 list_contacts

Lists all your Google contacts or filters them by name.

Parameters:

• name_filter (optional): String to filter contacts by name
• max_results (optional): Maximum number of contacts to return (default: 100)

Example:

👤 get_contact

Retrieves detailed information about a specific contact.

Parameters:

• identifier: Resource name (people/*) or email address of the contact

Example:

➕ create_contact

Creates a new contact in your Google Contacts.

Parameters:

• given_name: First name of the contact
• family_name (optional): Last name of the contact
• email (optional): Email address of the contact
• phone (optional): Phone number of the contact

Example:

✏️ update_contact

Updates an existing contact with new information.

Parameters:

• resource_name: Contact resource name (people/*)
• given_name (optional): Updated first name
• family_name (optional): Updated last name
• email (optional): Updated email address
• phone (optional): Updated phone number

Example:

🗑️ delete_contact

Deletes a contact from your Google Contacts.

Parameters:

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

Example:

🔍 search_contacts

Searches your contacts by name, email, or phone number.

Parameters:

• query: Search term to find in contacts
• max_results (optional): Maximum number of results to return (default: 10)

Example:

🏢 list_workspace_users

Lists Google Workspace users in your organization's directory.

Parameters:

• query (optional): Search term to find specific users
• max_results (optional): Maximum number of results to return (default: 50)

Example:

🔭 search_directory

Performs a targeted search of your organization's Google Workspace directory.

Parameters:

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

Example:

👥 get_other_contacts

Retrieves contacts from the 'Other contacts' section - people you've interacted with but haven't added to your contacts.

Parameters:

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

Example:

🔒 Permissions

When first running the server, you'll need to authenticate with Google and grant the necessary permissions to access your contacts. The authentication flow will guide you through this process.

❓ Troubleshooting

• 🔐 Authentication Issues: Ensure your credentials are valid and have the necessary scopes
• ⚠️ API Limits: Be aware of Google People API quota limits
• 📝 Logs: Check the console output for error messages and debugging information

👥 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.