MCP Google Contacts Server

📇 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)

Install uv if you don't have it already:
```
pip install uv
```

Clone the repository:

git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
cd mcp-google-contacts-server

Create a virtual environment and install dependencies:

uv venv
source .venv/bin/activate
uv pip install -r requirements.txt

📦 Using pip

Clone the repository:

git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
cd mcp-google-contacts-server

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

Create a Google Cloud project and enable the People API
Create OAuth 2.0 credentials (Desktop application type)
Download the credentials.json file
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

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

This starts the server with the default stdio transport.

⚙️ Command Line Arguments

| Argument | Description | Default Value | |----------|-------------|---------------| | --transport | Transport protocol to use (stdio or http) | stdio | | --host | Host for HTTP transport | localhost | | --port | Port for HTTP transport | 8000 | | --client-id | Google OAuth client ID (overrides environment variable) | - | | --client-secret | Google OAuth client secret (overrides environment variable) | - | | --refresh-token | Google OAuth refresh token (overrides environment variable) | - | | --credentials-file | Path to Google OAuth credentials.json file | - |

📝 Examples

Start with HTTP transport:

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

Use specific credentials file:

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

Provide credentials directly:

python src/main.py --client-id YOUR_CLIENT_ID --client-secret YOUR CLIENT_SECRET --refresh-token YOUR_REFRESH_TOKEN

🔌 Integration with MCP Clients

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

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

🧰 Available Tools

This MCP server provides the following tools:

| Tool | Description | |------|-------------| | list_contacts | List all contacts or filter by name | | get_contact | Get a contact by resource name or email | | create_contact | Create a new contact | | update_contact | Update an existing contact | | delete_contact | Delete a contact by resource name | | search_contacts | Search contacts by name, email, or phone number | | list_workspace_users | List Google Workspace users in your organization's directory | | search_directory | Search for people in the Google Workspace directory | | get_other_contacts | Retrieve contacts from the 'Other contacts' section |

🔍 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:

list_contacts(name_filter="John", max_results=10)

👤 `get_contact`

Retrieves detailed information about a specific contact.

Parameters:

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

Example:

get_contact("[email protected]")
# or
get_contact("people/c12345678901234567")

➕ `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:

create_contact(given_name="Jane", family_name="Smith", email="[email protected]", phone="+1-555-123-4567")

✏️ `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:

update_contact(resource_name="people/c12345678901234567", email="[email protected]")

🗑️ `delete_contact`

Deletes a contact from your Google Contacts.

Parameters:

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

Example:

delete_contact(resource_name="people/c12345678901234567")

🔍 `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:

search_contacts(query="john", max_results=5)

🏢 `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:

list_workspace_users(query="engineering", max_results=25)

🔭 `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:

search_directory(query="product manager", max_results=10)

👥 `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:

get_other_contacts(max_results=30)

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