Google Contacts MCP Server
Serverless MCP server for Google Contacts with per-user OAuth authentication on AWS Lambda
Developed by Offleash
Overview
A production-ready Model Context Protocol (MCP) server that enables AI assistants like Claude to access Google Contacts via a secure, serverless architecture. Each employee authenticates with their own Google account, and contact data flows through in real-time without storage.
Key Features
- Per-User OAuth 2.1 Authentication - Each employee uses their own Google Contacts
- Zero Contact Data Storage - Only OAuth tokens stored, contacts fetched in real-time
- Serverless AWS Lambda - Auto-scaling, pay-per-use, zero infrastructure management
- Privacy-First DynamoDB - Stores only tokens with automatic expiration (TTL)
- Works with Claude Web & Desktop - Single URL works for both access methods
- Read-Only Access - Uses
contacts.readonlyscope only
Architecture
Employee → Claude (Web/Desktop) → API Gateway → Lambda → Google Contacts API
↓
DynamoDB
(OAuth tokens only)
Components
- AWS Lambda - Hosts Express.js MCP server with Streamable HTTP transport
- API Gateway HTTP API - Exposes
/mcpendpoint with CORS and OAuth 2.1 endpoints - DynamoDB Tables:
sessions- Stores OAuth tokens with TTL (no contact data!)oauth-clients- Dynamic client registration (DCR)auth-codes- Temporary authorization codes (10-minute TTL)
- AWS Systems Manager Parameter Store - Stores Google OAuth client credentials
- AWS CDK - Infrastructure as Code for deployment
Quick Start
Prerequisites
- Node.js >= 18.0.0
- AWS Account with CLI configured
- Google Cloud Project with People API enabled
- AWS CDK installed:
npm install -g aws-cdk
1. Install Dependencies
npm install
2. Configure Google OAuth
- Go to Google Cloud Console
- Enable the People API
- Create OAuth 2.0 credentials (Web application type)
- Note your
client_idandclient_secret - Add redirect URI (you'll get this after deployment):
https://your-api-id.execute-api.region.amazonaws.com/google/callback
3. Deploy to AWS
# Build TypeScript
npm run build
# Build Lambda package
npm run build:lambda
# Deploy with CDK
npm run cdk:deploy
4. Configure OAuth Credentials
After deployment, update the Google OAuth credentials in AWS Systems Manager Parameter Store:
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
Note: The redirect URI is constructed dynamically as
${API_ENDPOINT}/google/callback- you don't need to include it in the parameter.
5. Add Redirect URI to Google
Copy the GoogleCallbackUrl from CDK outputs and add it to your Google OAuth credentials:
- Go to Google Cloud Console → APIs & Services → Credentials
- Edit your OAuth 2.0 Client ID
- Add the callback URL to "Authorized redirect URIs" (e.g.,
https://abc123.execute-api.us-west-2.amazonaws.com/google/callback)
Usage
Claude Web
- Go to Claude.ai → Settings → Integrations
- Click "Add server"
- Enter your MCP server URL:
https://your-api-id.execute-api.region.amazonaws.com/mcp - Click "Connect"
- Authenticate with your Google account when prompted
That's it! Claude will handle the OAuth 2.1 flow automatically.
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"google-contacts": {
"url": "https://your-api-id.execute-api.region.amazonaws.com/mcp"
}
}
}
Restart Claude Desktop. When you first use the server, you'll be redirected to authenticate with Google.
Available Tools
1. list_contacts
List contacts with pagination.
Parameters:
pageSize(optional): Number of contacts (1-1000, default: 100)pageToken(optional): Pagination tokensortOrder(optional): Sort order (FIRST_NAME_ASCENDING, etc.)
2. get_contact
Get details for a specific contact.
Parameters:
resourceName(required): Contact ID (e.g.,people/c1234567890)
3. search_contacts
Search across all contact fields.
Parameters:
query(required): Search termpageSize(optional): Number of results (default: 100)readMask(optional): Specific fields to return
4. search_directory
Search Google Workspace directory (Workspace accounts only).
Parameters:
query(required): Search termpageSize(optional): Number of results (default: 100)pageToken(optional): Pagination token
Privacy & Security
What We Store
✅ OAuth access tokens (encrypted, auto-expire) ✅ OAuth refresh tokens (encrypted, auto-expire) ✅ User email (for session management) ✅ Token expiration timestamps
What We DON'T Store
❌ Contact names, emails, phone numbers ❌ Search queries ❌ Any contact data whatsoever
All contact data flows through the server in real-time and is never persisted.
Development
# Install dependencies
npm install
# Build TypeScript
npm run build
# Build Lambda package
npm run build:lambda
# Type checking
npm run typecheck
# Deploy to AWS
npm run cdk:deploy
# Destroy AWS resources
npm run cdk:destroy
Project Structure
google-contacts-mcp/
├── bin/
│ └── app.ts # CDK app entry point
├── lib/
│ └── google-contacts-mcp-stack.ts # CDK infrastructure definition
├── src/
│ ├── lambda.ts # Lambda handler entry point
│ ├── app.ts # Express application setup
│ ├── mcp-service.ts # MCP protocol implementation
│ ├── oauth-provider.ts # OAuth 2.1 provider implementation
│ ├── oauth-client-store.ts # DynamoDB OAuth client registry
│ ├── auth-code-store.ts # DynamoDB authorization code storage
│ ├── session-manager.ts # DynamoDB session/token storage
│ ├── contacts.ts # Google Contacts API calls
│ └── types.ts # TypeScript type definitions
├── public/
│ └── logo.png # Server icon
├── package.json
├── tsconfig.json
├── cdk.json # CDK configuration
└── README.md
Costs
With AWS Lambda's pay-per-use model:
- Lambda: ~$0.20 per 1M requests
- API Gateway: ~$1.00 per 1M requests
- DynamoDB: ~$0.25 per 1M read/write requests
- Parameter Store (Standard String parameter): Free (standard throughput)
Typical monthly cost for a 50-person team: ~$3-8/month
Troubleshooting
"Authentication required"
Click the "Connect" button in Claude and authenticate with your Google account.
"Invalid or expired access token"
Your session expired. Click "Connect" again to re-authenticate.
"Failed to load OAuth credentials"
Update the parameter in AWS Systems Manager Parameter Store with your correct Google OAuth client ID and secret.
"Request is missing required authentication credential" (Google error)
Check that your Google Cloud Console OAuth consent screen includes the correct scopes:
https://www.googleapis.com/auth/contacts.readonlyhttps://www.googleapis.com/auth/userinfo.email
"Directory search only available for Google Workspace"
search_directory requires a Workspace account. Use search_contacts instead.
Support
- Documentation: See QUICKSTART.md
- Issues: GitHub Issues
- Commercial Support: Contact Offleash
License
This project is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International (CC BY-NC-SA 4.0).
What this means:
- ✅ Free to use for personal and internal company purposes
- ✅ Must give credit to Offleash
- ❌ Cannot be sold or used commercially
- ❌ Modifications must use the same license
See LICENSE file for full terms or visit https://creativecommons.org/licenses/by-nc-sa/4.0/
About Offleash
Built by Offleash - Empowering teams with AI-powered tools.
Version: 1.0.0 Last Updated: October 2025