google-contacts-mcp
Provides tools for managing Google Contacts via the Google People API, including creating, updating, merging, searching, listing, deleting, and organizing contacts, parsing contact data from formats like vCard/HTML/Markdown/CSV/JSON/freeform text, extracting contact details from images, and managing contact groups.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
google-contacts-mcp
A self-contained, zero-dependency Node.js / TypeScript MCP (Model Context Protocol) server (google-contacts-mcp.mjs) that connects Claude, ChatGPT, and Gemini to Google Contacts (Google People API v1).
Add, edit, merge, search, and organize Google Contacts from PNG / JPG images (business cards, screenshots, badges), markup (HTML signatures, Markdown, vCard .vcf, CSV, JSON), or freeform text.
Single self-contained
.mjsfile: Runnode google-contacts-mcp.mjsdirectly on Node.js ≥ 20 — nonpm installornode_modulesrequired.TypeScript source included: Full TypeScript source lives in
src/google-contacts-mcp.tsand compiles cleanly togoogle-contacts-mcp.mjsvia Node's built-in type stripper (npm run build).Dual transport: Speaks stdio by default (Claude Desktop, Claude Code, Gemini CLI, ChatGPT Desktop) and Streamable HTTP / SSE (
--http) for remote/connector harnesses.
Tools Exposed
Tool | Purpose |
| Smart Add-or-Edit: Searches by email → phone → full name. Updates & merges if found; creates a new contact if not. |
| Create a new contact with full details (names, emails, phones, company, title, addresses, URLs, birthday, notes, custom fields, avatar photo). |
| Edit an existing contact by |
| Parse raw vCard ( |
| Extract contact details from PNG / JPG / WEBP / GIF (local file path, |
| Full-text search across names, emails, phone numbers, organizations, and notes. |
| Fetch complete details for a contact by |
| Paginated contact listing with configurable sort order. |
| Delete a contact by |
| List, create, or add/remove contacts from Google Contact labels/groups ( |
Related MCP server: MCP Google Contacts Server
How Multi-Format Inputs Work (PNG, JPG, Text, Markup)
Images (
PNG,JPG,WEBP,GIF):Attached directly in Claude / ChatGPT / Gemini chat: The harness's multimodal vision reads the business card or screenshot directly and calls
upsert_contact(and can optionally passphotoBase64/photoPathto set the contact's avatar).Local file path or Base64 passed to
extract_contact_from_image:Uses MCP Sampling (
sampling/createMessage) if supported by the connected client.Or uses a server-side Vision API if
GEMINI_API_KEY,ANTHROPIC_API_KEY, orOPENAI_API_KEYis set.Otherwise returns a native MCP
ImageContentblock ({ type: "image", data, mimeType }) so Claude, ChatGPT, or Gemini visually inspects the image and callsupsert_contact.
Text & Markup (
vCard,HTML,Markdown,CSV,JSON,Text):Call
parse_and_upsert_contactwith raw content (or let the LLM extract fields and callupsert_contact).Built-in parsers extract
mailto:/tel:links, hCard microformats (p-name,p-org,p-job-title), vCard 2.1/3.0/4.0 properties, Markdown tables/links, CSV rows, and natural-language signatures.
Quick Start
1. Enable Google People API & Create OAuth Client
Open the Google Cloud Console.
Enable the Google People API.
Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.
Choose Desktop app (or Web application with Authorized redirect URI
http://127.0.0.1:8765/oauth2callback).Copy your Client ID and Client Secret (or download the
client_secret.jsonfile).
2. Authenticate Once (--auth)
export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"
node /Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs --authOr pass your downloaded credentials file directly:
node /Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs --auth --credentials ~/Downloads/client_secret.jsonThis opens your browser, authorizes the https://www.googleapis.com/auth/contacts scope, and saves your refresh token to ~/.config/google-contacts-mcp/tokens.json (0600 permissions).
Verify status at any time:
node /Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs --statusWiring Clients (Claude, ChatGPT, Gemini)
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"google-contacts": {
"command": "node",
"args": ["/Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs"],
"env": {
"GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_CLIENT_SECRET": "your-client-secret"
}
}
}
}Claude Code
claude mcp add google-contacts \
--scope user \
--env GOOGLE_CLIENT_ID="$GOOGLE_CLIENT_ID" \
--env GOOGLE_CLIENT_SECRET="$GOOGLE_CLIENT_SECRET" \
-- node /Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjsGemini CLI & Gemini Code Assist
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"google-contacts": {
"command": "node",
"args": ["/Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs"],
"env": {
"GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
"GOOGLE_CLIENT_SECRET": "your-client-secret"
}
}
}
}ChatGPT (Desktop MCP or Streamable HTTP / SSE Connector)
Stdio mode (local MCP runner / Desktop): Point the command to
node /Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs.Streamable HTTP / SSE mode (for ChatGPT Developer Mode / HTTP connectors):
node /Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs --http --port 3000Endpoints exposed:
POST http://127.0.0.1:3000/mcp(Streamable HTTP JSON-RPC)GET http://127.0.0.1:3000/sse+POST /messages(SSE transport)GET http://127.0.0.1:3000/health(Health check)
Development & Testing
# Rebuild standalone google-contacts-mcp.mjs from src/google-contacts-mcp.ts
npm run build
# Run unit & integration test suite (zero external dependencies)
npm testProject Layout
google-contacts-mcp/
├── google-contacts-mcp.mjs # Standalone, zero-dependency executable MCP server
├── src/
│ └── google-contacts-mcp.ts # Full TypeScript source
├── scripts/
│ └── build.mjs # Zero-dep builder using Node's stripTypeScriptTypes
├── test/
│ └── google-contacts-mcp.test.mjs
├── .env.example
├── package.json
├── tsconfig.json
└── README.mdLicense
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Personal CRM for Claude. Contacts live as plain-text files in your own Google Drive.
Create contacts, move deals, send proposals and invoices, read your inbox, from Claude or ChatGPT.
Streamline your Attio workflows using natural language to search, create, update, and organize com…
A private address book your AI can search, update and import into.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides comprehensive Google Contacts management including creating, searching, and updating contacts with 25+ fields, managing contact groups, and accessing Google Workspace directories.191MIT
- AlicenseNot gradedqualityDmaintenanceGives AI assistants access to Google Contacts, supporting listing, searching, creating, updating, and deleting contacts, as well as searching Google Workspace directories.MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage contacts with full CRUD, dedup, merge, import/export, sync with Google/Apple/CardDAV, and git-backed rollback.AGPL 3.0
- AlicenseNot gradedqualityDmaintenanceA remote MCP server for Google Contacts, deployed on Cloudflare Workers, that enables Claude to create, search, list, get, and update your Google contacts via the People API. Designed as a custom connector for claude.ai, it supports OAuth and can extract contact details from business card photos.2MIT