Google Contacts 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:

1. Categorized 750 contacts into 8 organized groups
2. Deleted 446 obsolete contacts automatically
3. Cleaned duplicate and malformed entries
4. Reviewed remaining contacts efficiently in Excel
5. 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

1. Follow the Setup Guide to configure Google Cloud OAuth
2. 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"]
    }
  }
}

3. 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 ([email protected])
- Sarah Martinez ([email protected])

Create a new contact

You: "Add a contact for Hans Mueller, senior engineer at SwissTech, email [email protected], 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.

Educational Value

This repository is designed to teach you:

1. MCP Protocol Basics - Understanding tool definitions and handlers
2. OAuth 2.0 Flow - Implementing secure API authentication
3. Google APIs - Working with the People API
4. TypeScript - Building type-safe MCP servers
5. Real-World Application - Solving actual productivity problems

Perfect for:

• AI/ML engineers learning MCP
• Developers wanting to extend Claude's capabilities
• Anyone building custom AI integrations
• Training courses on AI tool development

Security & Privacy

• OAuth 2.0 - Industry-standard authentication
• Token storage - Secure local token management
• No data collection - All data stays between you and Google
• Minimal scopes - Only requests necessary permissions
• Open source - Audit the code yourself

Contributing

Contributions welcome! Please read our Contributing Guide first.

License

MIT License - see LICENSE file for details.

Acknowledgments

• Built on the Model Context Protocol by Anthropic
• Uses Google's People API
• Inspired by real-world contact management challenges

Author

Chris Spirito

• Hacker, Teacher, Storyteller
• 30+ years in cyber defense and nuclear security
• Visiting Professor at University of Tartu (2014-2024)
• Training: hecke.ai

---

Ready to get started? Head to the Setup Guide to begin!