Skip to main content
Glama

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 .mjs file: Run node google-contacts-mcp.mjs directly on Node.js ≥ 20 — no npm install or node_modules required.

  • TypeScript source included: Full TypeScript source lives in src/google-contacts-mcp.ts and compiles cleanly to google-contacts-mcp.mjs via 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

upsert_contact

Smart Add-or-Edit: Searches by email → phone → full name. Updates & merges if found; creates a new contact if not.

create_contact

Create a new contact with full details (names, emails, phones, company, title, addresses, URLs, birthday, notes, custom fields, avatar photo).

update_contact

Edit an existing contact by resourceName (people/c...). Automatically fetches etag and safely merges or replaces fields.

parse_and_upsert_contact

Parse raw vCard (.vcf), HTML, Markdown, CSV, JSON, or freeform email signatures and upsert into Google Contacts (dryRun supported).

extract_contact_from_image

Extract contact details from PNG / JPG / WEBP / GIF (local file path, file:// URL, data: URI, or base64) via MCP Sampling, Vision API, or native MCP ImageContent harness pass-through.

search_contacts

Full-text search across names, emails, phone numbers, organizations, and notes.

get_contact

Fetch complete details for a contact by resourceName.

list_contacts

Paginated contact listing with configurable sort order.

delete_contact

Delete a contact by resourceName.

manage_contact_groups

List, create, or add/remove contacts from Google Contact labels/groups (contactGroups).


Related MCP server: MCP Google Contacts Server

How Multi-Format Inputs Work (PNG, JPG, Text, Markup)

  1. 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 pass photoBase64 / photoPath to set the contact's avatar).

    • Local file path or Base64 passed to extract_contact_from_image:

      1. Uses MCP Sampling (sampling/createMessage) if supported by the connected client.

      2. Or uses a server-side Vision API if GEMINI_API_KEY, ANTHROPIC_API_KEY, or OPENAI_API_KEY is set.

      3. Otherwise returns a native MCP ImageContent block ({ type: "image", data, mimeType }) so Claude, ChatGPT, or Gemini visually inspects the image and calls upsert_contact.

  2. Text & Markup (vCard, HTML, Markdown, CSV, JSON, Text):

    • Call parse_and_upsert_contact with raw content (or let the LLM extract fields and call upsert_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

  1. Open the Google Cloud Console.

  2. Enable the Google People API.

  3. Go to APIs & Services → Credentials → Create Credentials → OAuth client ID.

  4. Choose Desktop app (or Web application with Authorized redirect URI http://127.0.0.1:8765/oauth2callback).

  5. Copy your Client ID and Client Secret (or download the client_secret.json file).

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 --auth

Or pass your downloaded credentials file directly:

node /Users/ritesh/Projects/google-contacts-mcp/google-contacts-mcp.mjs --auth --credentials ~/Downloads/client_secret.json

This 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 --status

Wiring 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.mjs

Gemini 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 3000

    Endpoints 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 test

Project 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.md

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Gives AI assistants access to Google Contacts, supporting listing, searching, creating, updating, and deleting contacts, as well as searching Google Workspace directories.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage contacts with full CRUD, dedup, merge, import/export, sync with Google/Apple/CardDAV, and git-backed rollback.
      AGPL 3.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      2
      MIT