google-contacts

This MCP server provides a serverless, per-user OAuth-enabled integration to Google Contacts. It runs as an Express-based MCP service behind AWS API Gateway and Lambda, exposing a /mcp endpoint that Claude can reach. The server supports read-only access to Google Contacts using the contacts.readonly scope and fetches contact data in real-time based on the authenticated user. Available tools include list_contacts for paginated listing, get_contact for details on a specific contact, search_contacts for across-all-fields queries, and search_directory (Workspace accounts only) for directory lookups. To use it, set up OAuth credentials in Google Cloud, deploy to AWS, and configure Claude or Claude Desktop to point at the /mcp URL. The flow handles the OAuth dance per user, stores only tokens in DynamoDB with TTL, and does not persist contact data.

Prerequisites:

• Node.js (>= 18) installed
• AWS account with IAM permissions and AWS CLI configured
• Google Cloud Project with People API enabled
• CDK installed globally (npm install -g aws-cdk)

1. Install dependencies

npm install

2. Build the project (TypeScript to JavaScript)

npm run build

3. Build the Lambda package (if using CDK constructs)

npm run build:lambda

4. Deploy to AWS using CDK

npm run cdk:deploy

5. Configure OAuth credentials in AWS Parameter Store after deployment

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

6. Add the Google OAuth redirect URI from the deployed API endpoint to your Google Cloud credentials (Authorized redirect URIs)

7. Update Claude/Claude Desktop configuration to point at the MCP endpoint, e.g. https://your-api-id.execute-api.region.amazonaws.com/mcp

Tips and notes:

• The server uses per-user OAuth 2.1 flow; tokens are stored in DynamoDB with TTL and no contact data is persisted.
• Ensure your Google Cloud OAuth consent screen includes the required scopes: https://www.googleapis.com/auth/contacts.readonly and https://www.googleapis.com/auth/userinfo.email
• Redirect URIs are generated dynamically based on your API endpoint; you don’t need to hard-code them in the parameter store.
• If you see “Authentication required” in Claude, use the Connect button to re-authenticate and renew tokens.
• This MCP server is designed to be read-only with respect to Google Contacts data; there is no write-back to Google Contacts.
• Common issues: invalid/expired tokens, misconfigured redirect URIs, or missing OAuth credentials in Parameter Store. Re-authenticate or update credentials as needed.