MCP 服务器

Google Contacts MCP Server

A Model Context Protocol (MCP) server that integrates Google Contacts with Claude, enabling contact management directly from your AI assistant.

README

Google Contacts MCP Server

"My two requirements were, interface via MCP to my Google Contacts for ease of adding/updating contacts,and perform some curation on my contact list. I had 750 contacts from all the way back to the early 2000's. These included defunct taxi services, and people I'd never contact again. This MCP server helped me clean it down to 297 relevant contacts in one afternoon." - Chris Spirito

A Model Context Protocol (MCP) server that integrates Google Contacts with Claude, enabling contact management directly from your AI assistant.

Learn by doing: This repository not only provides a working MCP server, but teaches you how to build your own from scratch.

Features

🔍 Search contacts by name, email, or phone
📋 List all contacts with pagination
➕ Create new contacts with full details
🗑️ Delete contacts individually
📖 Get detailed contact info including addresses and organizations
🔐 Secure OAuth 2.0 authentication

Real-World Use Case

This MCP server was built to solve a real problem: contact database cleanup. Over 20 years of professional work, my Google Contacts had accumulated:

Old conference contacts from events a decade ago
Defunct service vendors (taxi services, contractors)
Duplicate entries with formatting issues
Personal contacts mixed with professional ones
Contacts with missing or outdated information

Using this MCP server with Claude Code, I:

Categorized 750 contacts into 8 organized groups
Deleted 446 obsolete contacts automatically
Cleaned duplicate and malformed entries
Reviewed remaining contacts efficiently in Excel
Reduced my contact database by 60% in a few hours

The result? A clean, manageable contact database of 297 relevant contacts.

Quick Start

Prerequisites

Node.js 18+ and npm
A Google Cloud account
Claude Code (or any MCP-compatible client)

Installation

# Clone the repository
git clone https://github.com/yourusername/google-contacts-mcp.git
cd google-contacts-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Setup

Follow the Setup Guide to configure Google Cloud OAuth
Add to Claude Code's MCP settings (~/.config/claude-code/mcp_settings.json):

{
  "mcpServers": {
    "google-contacts": {
      "command": "node",
      "args": ["/path/to/google-contacts-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code and start using Google Contacts tools!

Available Tools

search_contacts - Search for contacts by name, email, or phone
list_contacts - List all contacts with pagination
get_contact - Get detailed information about a specific contact
create_contact - Create a new contact
delete_contact - Delete a contact by resource name

Documentation

Introduction - Why we built this and what you'll learn
Setup Guide - Step-by-step Google Cloud and OAuth configuration
Architecture - How the MCP server works under the hood
Building Your Own - Tutorial: Create your own MCP server from scratch
Troubleshooting - Common issues and solutions

Example Usage

Search for a contact

You: "Search for contacts named Sarah"
Claude: [uses search_contacts tool]
Found 2 contacts:
- Sarah Johnson (sarah.johnson@example.com)
- Sarah Martinez (smartinez@techcorp.com)

Create a new contact

You: "Add a contact for Hans Mueller, senior engineer at SwissTech, email h.mueller@swisstech.ch, phone +41 44 123 4567"
Claude: [uses create_contact tool]
Contact created successfully for Hans Mueller.

Delete obsolete contacts

You: "Delete all contacts from the 2015 conference in Berlin"
Claude: [searches, confirms, then uses delete_contact for each]
Deleted 12 contacts from the conference attendee list.