📇 MCP Google Contacts Server

by RayanZaki

33 428 downloads Not rated yet MIT

GitHub

Other

About

MCP Google Contacts Server is 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.

Details

License: MIT

Explore

- 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

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name 📇 MCP Google Contacts Server

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

From the repository

- 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

To install the mcp-google-contacts-server as a Python package:

1. Clone the repository:

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

    cd mcp-google-contacts-server

2. Rename the source directory:
The package expects the source code to be in a directory named mcp_google_contacts_server.

    mv src mcp_google_contacts_server

3. Install the package:
This will install the package and its dependencies, making the mcp-google-contacts command available in your PATH.

    pip install .

Note: If you encounter import errors after installation, ensure that relative imports within the source files (main.py, tools.py, google_contacts_service.py, formatters.py, config.py) are updated to use absolute imports (e.g., from mcp_google_contacts_server.module_name import ...). This is typically handled automatically by pip install . but can sometimes require manual adjustment if the package structure is unusual.

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

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

Note: If your existing environment variables for Google OAuth client ID and client secret have different names (e.g., GOOGLE_OAUTH_CLIENT_ID), you can alias them in your .env file (e.g., GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID) to ensure the server picks them up correctly.
Use e.g. export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET in command line before: mcp-google-contacts :

env | grep GOOGLE
export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET
env | grep GOOGLE
mcp-google-contacts

{authentication evocation should happen here)

`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

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 |

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "\ud83d\udcc7 mcp google contacts server": {
            "mcp-google-contacts-server": {
                "command": "uv",
                "args": [
                    "venv"
                ]
            }
        }
    }
}

McpServers

{
    "mcp-google-contacts-server": {
        "command": "uv",
        "args": [
            "venv"
        ]
    }
}

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. Much updated from its original by Gemini AI in Gemini CLI.

✨ Features

🚀 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

📦 Installation from Source

To install the mcp-google-contacts-server as a Python package:

1. Clone the repository:

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

    cd mcp-google-contacts-server

2. Rename the source directory:
The package expects the source code to be in a directory named mcp_google_contacts_server.

    mv src mcp_google_contacts_server

3. Install the package:
This will install the package and its dependencies, making the mcp-google-contacts command available in your PATH.

    pip install .

🔑 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

env | grep GOOGLE
export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET
env | grep GOOGLE
mcp-google-contacts

{authentication evocation should happen here)

🚀 Initial Authorization (Recommended)

For the initial authorization flow to obtain your GOOGLE_REFRESH_TOKEN, it is recommended to run the mcp-google-contacts command directly in your terminal (outside of any MCP client that might obscure the interactive browser prompts).

Example:

mcp-google-contacts

Follow the instructions in your terminal and browser to complete the authentication. Once the GOOGLE_REFRESH_TOKEN is displayed, you can set it as an environment variable for non-interactive use.

🛠️ Usage

🏃‍♂️ Basic Startup

```bash
python src/main.py

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

list_contacts

get_contact

create_contact

update_contact

delete_contact

search_contacts

list_workspace_users

search_directory

get_other_contacts

Claude Desktop / Cursor

McpServers

✨ Features

🚀 Installation

📋 Prerequisites

📦 Installation from Source

🔑 Authentication Setup

🔐 Option 1: Using a credentials.json file

🔐 Option 2: Using environment variables

🚀 Initial Authorization (Recommended)

🛠️ Usage

🏃‍♂️ Basic Startup

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

`list_contacts`

`get_contact`

`create_contact`

`update_contact`

`delete_contact`

`search_contacts`

`list_workspace_users`

`search_directory`

`get_other_contacts`