Google Contacts

Serverless MCP (Model Context Protocol) connector for Google Contacts on AWS Lambda. Per-user OAuth 2.1 authentication with privacy-first design. Enables AI agents & LLMs like Claude to access Google Contacts via People API in real-time. Zero contact data storage. Works with Claude Web & Desktop.

typescript

2

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

You deploy a serverless MCP server that lets AI assistants access Google Contacts securely via per-user OAuth, with real-time data access and no contact storage. It is built to scale on AWS Lambda, uses a privacy-first approach for tokens, and provides a single MCP URL that your client can connect to for both Web and Desktop usage.

How to use

You connect your MCP client (for example Claude Web or Claude Desktop) to the Google Contacts MCP server using the provided MCP URL. The server handles the OAuth 2.1 flow for each user, obtaining the necessary Google Contacts permissions with read-only access. When you issue MCP actions like listing contacts or searching, the server fetches data from Google Contacts in real time and returns results without persisting contact data.

In practice, you authenticate once per user via Google. After successful authorization, your client can request operations such as listing contacts, retrieving a single contact, or performing searches. The system ensures tokens are stored securely and expire automatically, while no actual contact information is stored by the server.

How to install

Prerequisites: you need Node.js version 18 or newer and an AWS account with the CLI configured. You also need a Google Cloud project with the People API enabled.

Step-by-step commands you will run to prepare and deploy the MCP server are provided here. Execute them in your preferred shell.

# Build TypeScript sources
npm run build

# Build Lambda package
npm run build:lambda

# Deploy infrastructure (CDK)
npm run cdk:deploy

Configure OAuth credentials and redirects

You store the Google OAuth client credentials in AWS Systems Manager Parameter Store and reference them when the server starts. Follow these steps to create and store the credentials.

aws ssm put-parameter \
  --name "/google-contacts-mcp/oauth-credentials" \
  --value '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}' \
  --type String \
  --overwrite \
  --region us-west-2

MCP URL to use

Use the following MCP endpoint when connecting from your client. This is the HTTP URL exposed by API Gateway after deployment.

https://your-api-id.execute-api.region.amazonaws.com/mcp

Available tools

list_contacts

List contacts with optional pagination and sorting. Supports pageSize, pageToken, and sortOrder.

get_contact

Retrieve details for a specific contact by its resource name.

search_contacts

Search across all contact fields with optional pageSize and readMask to limit fields.

search_directory

Search Google Workspace directory for Workspace accounts (requires Google Workspace).