MCP Google Contacts Server

A Model Context Protocol (MCP) server that gives AI assistants access to Google Contacts. Supports listing, searching, creating, updating, and deleting contacts, as well as searching Google Workspace directories.

Forked from RayanZaki/mcp-google-contacts-server with the following bug fixes:

• search_contacts now uses the Google People API's native searchContacts endpoint instead of fetching the first 100 contacts and filtering locally — searches across all contacts regardless of list size

• list_contacts now paginates through all results instead of stopping at the first page

• get_contact by email address now uses the server-side search instead of scanning a partial contact list

• Removed a stray debug print statement in list_directory_people

Prerequisites

• Python 3.12 or higher

• A Google Cloud project with the People API enabled

• OAuth 2.0 credentials (Desktop app type) downloaded from Google Cloud Console

Related MCP server: macOS Contacts MCP

Installation

git clone https://github.com/puzne2000/mcp-google-contacts-server.git
cd mcp-google-contacts-server
pip install .

This installs the mcp-google-contacts command into your PATH.

Authentication

Step 1 — Create a Google Cloud project and get credentials

If you don't already have OAuth credentials from Google, follow these steps. If you do, skip to Step 2.

1. Go to https://console.cloud.google.com/ and sign in.

2. Click the project dropdown (top-left) → New Project → give it a name → Create.

3. In the left menu, go to APIs & Services → Library, search for People API, click it, and click Enable.

4. In the left menu, go to APIs & Services → OAuth consent screen:

   • Choose External → Create

   • Fill in App name, User support email, and Developer contact email (your email for all three)

   • Click Save and Continue through all steps, then Back to Dashboard

   • The app stays in Testing mode, which is fine for personal use. If you want others to use it with their accounts, add them as test users on the Test users screen.

5. In the left menu, go to APIs & Services → Credentials:

   • Click + Create Credentials → OAuth client ID

   • Set Application type to Desktop app → Create

   • Click Download JSON in the confirmation popup

6. Place the downloaded file at:

mkdir -p ~/.config/google
mv ~/Downloads/client_secret_*.json ~/.config/google/credentials.json

Alternatively, pass its path explicitly with --credentials-file, or use environment variables:

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REFRESH_TOKEN=...

"Google hasn't verified this app": When authorizing in the next step, you may see this warning. It is expected for personal apps in Testing mode — click Advanced → Go to [App Name] (unsafe) to proceed.

Step 2 — Run the initial auth flow

Run this once in your terminal to open a browser and authorize access:

mcp-google-contacts

Sign in with the Google account whose contacts you want to manage. The token is saved to ~/.config/google-contacts-mcp/token.json and auto-refreshes — you won't need to repeat this unless you revoke access.

Once you see Running with stdio transport, press Ctrl+C. Setup is complete.

MCP Configuration

The mcpServers block below is the same across all MCP-compatible clients. Where you put it depends on your client:

{
  "mcpServers": {
    "google-contacts": {
      "command": "mcp-google-contacts",
      "args": []
    }
  }
}

Available Tools

License

MIT — see LICENSE.