# 📇 MCP Google Contacts Server
A Machine Conversation Protocol (MCP) server that provides comprehensive Google Contacts functionality for AI assistants.
## ✨ Features
- **Complete Contact Management**: Create, read, update, and delete contacts with 25+ fields
- **Advanced Search**: Multi-field search across names, emails, phones, and organizations
- **Contact Groups**: Full label/group management and organization
- **Google Workspace Integration**: Directory search and user management
- **Efficient Performance**: Pagination support for large contact lists (1000+ contacts)
- **Rich Field Support**: Multiple emails/phones, addresses, birthdays, relationships, custom fields
## 🚀 Installation
### Prerequisites
- Python 3.12 or higher
- Google account with contacts access
- Google Cloud project with People API enabled
- OAuth 2.0 credentials
### Setup
1. **Clone and install:**
```bash
git clone git@github.com:4tal/mcp-google-contacts-server.git
cd mcp-google-contacts-server
# Using uv (recommended)
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
# Or using pip
pip install -r requirements.txt
```
2. **Set up Google API credentials** (choose one):
**Option A: Credentials file**
- Download `credentials.json` from Google Cloud Console
- Place in project root or specify with `--credentials-file`
**Option B: Environment variables**
```bash
export GOOGLE_CLIENT_ID="your_client_id"
export GOOGLE_CLIENT_SECRET="your_client_secret"
export GOOGLE_REFRESH_TOKEN="your_refresh_token"
```
## 🛠️ Usage
### Basic Startup
```bash
python src/main.py
# or
uv run src/main.py
```
### Command Line Options
- `--transport`: Protocol (`stdio` or `http`, default: `stdio`)
- `--host`: HTTP host (default: `localhost`)
- `--port`: HTTP port (default: `8000`)
- `--credentials-file`: Path to credentials.json
- `--client-id`, `--client-secret`, `--refresh-token`: OAuth credentials
### Examples
```bash
# HTTP transport
python src/main.py --transport http --port 8080
# Specific credentials file
python src/main.py --credentials-file /path/to/credentials.json
```
## 🔌 MCP Client Integration
Add to your MCP configuration:
```json
{
"mcpServers": {
"google-contacts-server": {
"command": "uv",
"args": [
"--directory", "/path/to/mcp-google-contacts-server",
"run", "main.py"
]
}
}
}
```
## 🧰 Available Tools
### Contact Management
- **`list_contacts`** - List all contacts with filtering and pagination
- **`search_contacts`** - Advanced multi-field search
- **`get_contact`** - Get detailed contact information
- **`create_contact`** - Create contact with basic fields (11 fields)
- **`create_contact_advanced`** - Create contact with all fields (25+ fields)
- **`update_contact`** - Update contact with basic fields
- **`update_contact_advanced`** - Update contact with all fields
- **`delete_contact`** - Delete a contact
### Contact Groups (Labels)
- **`list_contact_groups`** - List all contact groups/labels
- **`create_contact_group`** - Create new contact group
- **`get_contact_group`** - Get group details and members
- **`update_contact_group`** - Update group name
- **`delete_contact_group`** - Delete user-created groups
- **`add_contacts_to_group`** - Add contacts to a group
- **`remove_contacts_from_group`** - Remove contacts from group
- **`search_contacts_by_group`** - Find contacts in specific group
### Google Workspace
- **`list_workspace_users`** - List organization directory
- **`search_directory`** - Search workspace directory
- **`get_other_contacts`** - Get "other contacts"
## 📝 Quick Examples
### Search Contacts
```python
# Basic search
search_contacts("john smith")
# Search specific fields
search_contacts("engineer", search_fields=["jobTitle", "organization"])
# Search phone numbers
search_contacts("+1234567890")
```
### Create Contact
```python
# Basic contact
create_contact(
given_name="John",
family_name="Smith",
email="john@example.com",
phone="+1-555-123-4567",
organization="Acme Corp",
job_title="Software Engineer"
)
# Advanced contact with multiple fields
create_contact_advanced({
"given_name": "Jane",
"family_name": "Doe",
"emails": [
{"value": "jane@work.com", "type": "work"},
{"value": "jane@personal.com", "type": "home"}
],
"phones": [
{"value": "+1-555-111-2222", "type": "mobile"}
],
"organization": "Tech Corp",
"birthday": "1985-03-22"
})
```
### Manage Contact Groups
```python
# Create group
create_contact_group("Work Team")
# Add contacts to group
add_contacts_to_group("contactGroups/12345", ["people/67890", "people/11111"])
# Find contacts in group
search_contacts_by_group("contactGroups/12345")
```
## ❓ Troubleshooting
### Authentication Issues
- Ensure People API is enabled in Google Cloud Console
- Check OAuth credentials are valid and have proper scopes
- Required scopes: `contacts` and `directory.readonly`
### Search Not Working
- Use server-side search with `search_contacts`
- Try different search terms or fields
### Performance Issues
- Use pagination with `max_results` parameter
- Set `include_all_fields=False` for faster queries
## 🔧 Development
```bash
# Development setup
uv sync --dev
# Format code
./scripts/format.sh
# Run linting
./scripts/lint.sh
# Test
uv run python test_contact_groups.py
```
## 📄 License
MIT License - see LICENSE file for details.
---
**Note**: This server provides comprehensive Google Contacts functionality with support for all contact fields, advanced search, contact groups, and efficient handling of large contact lists.
