Google Contacts MCP
Manage Google Contacts in plain language: search, edit, label and batch-import
- Pricing
- Open source
- Platforms
- CLI, macOS, Windows
- Runs
- Locally
- Version
- 1.1.2
- Listing updated
- today
Similar MCP servers
About Google Contacts MCP
Google Contacts MCP is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.
Connection happens inside the chat. You ask the assistant to connect Google Contacts and it walks through creating an OAuth client, catches Google's redirect on 127.0.0.1 with PKCE and keeps the tokens itself, so no config files or restarts are needed. Alternatively you can supply an OAuth client id, secret and refresh token, or a short-lived access token for testing.
The 25 tools cover listing, searching and reading contacts, creating, updating and deleting them singly or in batches, managing contact groups and membership, and reading Google's automatically saved Other contacts and copying them into My Contacts. Updates are guarded by an etag, so a contact changed elsewhere causes the write to fail rather than being overwritten. Reads use field masks to stay compact.
The README is open about limits: deletes are permanent because the People API has no trash, search can lag recent writes by seconds and returns at most 30 results, Other contacts cannot be edited in place, and photos have no dedicated tool. It requests the narrow contacts scope, or read-only if you prefer.
Install
Run in a terminal
claude mcp add mcp-google-contacts --env GOOGLE_CONTACTS_CLIENT_SECRET='<GOOGLE_CONTACTS_CLIENT_SECRET>' --env GOOGLE_CONTACTS_REFRESH_TOKEN='<GOOGLE_CONTACTS_REFRESH_TOKEN>' --env GOOGLE_CONTACTS_ACCESS_TOKEN='<GOOGLE_CONTACTS_ACCESS_TOKEN>' -- npx -y mcp-google-contactsAdd to claude_desktop_config.json
{
"mcpServers": {
"mcp-google-contacts": {
"command": "npx",
"args": [
"-y",
"mcp-google-contacts"
],
"env": {
"GOOGLE_CONTACTS_CLIENT_SECRET": "<GOOGLE_CONTACTS_CLIENT_SECRET>",
"GOOGLE_CONTACTS_REFRESH_TOKEN": "<GOOGLE_CONTACTS_REFRESH_TOKEN>",
"GOOGLE_CONTACTS_ACCESS_TOKEN": "<GOOGLE_CONTACTS_ACCESS_TOKEN>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"mcp-google-contacts": {
"command": "npx",
"args": [
"-y",
"mcp-google-contacts"
],
"env": {
"GOOGLE_CONTACTS_CLIENT_SECRET": "<GOOGLE_CONTACTS_CLIENT_SECRET>",
"GOOGLE_CONTACTS_REFRESH_TOKEN": "<GOOGLE_CONTACTS_REFRESH_TOKEN>",
"GOOGLE_CONTACTS_ACCESS_TOKEN": "<GOOGLE_CONTACTS_ACCESS_TOKEN>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"mcp-google-contacts": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-google-contacts"
],
"env": {
"GOOGLE_CONTACTS_CLIENT_SECRET": "<GOOGLE_CONTACTS_CLIENT_SECRET>",
"GOOGLE_CONTACTS_REFRESH_TOKEN": "<GOOGLE_CONTACTS_REFRESH_TOKEN>",
"GOOGLE_CONTACTS_ACCESS_TOKEN": "<GOOGLE_CONTACTS_ACCESS_TOKEN>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"mcp-google-contacts": {
"command": "npx",
"args": [
"-y",
"mcp-google-contacts"
],
"env": {
"GOOGLE_CONTACTS_CLIENT_SECRET": "<GOOGLE_CONTACTS_CLIENT_SECRET>",
"GOOGLE_CONTACTS_REFRESH_TOKEN": "<GOOGLE_CONTACTS_REFRESH_TOKEN>",
"GOOGLE_CONTACTS_ACCESS_TOKEN": "<GOOGLE_CONTACTS_ACCESS_TOKEN>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"mcp-google-contacts": {
"command": "npx",
"args": [
"-y",
"mcp-google-contacts"
],
"env": {
"GOOGLE_CONTACTS_CLIENT_SECRET": "<GOOGLE_CONTACTS_CLIENT_SECRET>",
"GOOGLE_CONTACTS_REFRESH_TOKEN": "<GOOGLE_CONTACTS_REFRESH_TOKEN>",
"GOOGLE_CONTACTS_ACCESS_TOKEN": "<GOOGLE_CONTACTS_ACCESS_TOKEN>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
GOOGLE_CONTACTS_CLIENT_IDGoogle OAuth2 client id (refresh-token flow).GOOGLE_CONTACTS_CLIENT_SECRETGoogle OAuth2 client secret (refresh-token flow). Treat it as a secret.GOOGLE_CONTACTS_REFRESH_TOKENGoogle OAuth2 refresh token, exchanged for access tokens automatically. Treat it as a secret.GOOGLE_CONTACTS_ACCESS_TOKENStatic OAuth2 access token (~1h lifetime) — alternative to the refresh-token trio, mostly for testing.GOOGLE_CONTACTS_OAUTH_PORTFixed port for the loopback listener of the in-chat login (127.0.0.1 + PKCE). Set it when the client runs over SSH port forwarding; otherwise a free port is picked per login.GOOGLE_CONTACTS_API_BASEAPI root override.GOOGLE_CONTACTS_TIMEOUT_MSPer-request timeout in milliseconds.GOOGLE_CONTACTS_MAX_RETRIESRetries on transient errors (429 always; 5xx/network for reads).
What it does
- In-chat OAuth
- Connect from the conversation with PKCE on a loopback port.
- Etag-guarded updates
- Stale writes fail instead of overwriting.
- Batch operations
- Create, update or delete many contacts in one call.
- Label management
- Create and rename groups and manage membership.
- Other contacts
- Read auto-saved addresses and copy them into contacts.
- Minimal scopes
- Contacts scope, or read-only, plus a separate Other-contacts scope.
Good for
- Find everyone from a company with emails and phones
- Update a phone number and add a contact to a label
- Import fifty people in one batch
- Promote an auto-saved address to a real contact
Pricing
Open source
Free to run with your own Google account
Google Contacts MCP FAQ
Is delete reversible?
No. The People API has no trash, so deletes are permanent and the tools are marked destructive.
How many search results can I get?
At most 30, and the search cache can lag recent writes by a few seconds.
Which Google permissions are needed?
The contacts scope for read/write, or contacts.readonly for read-only, plus contacts.other.readonly for Other contacts.
Which clients are documented?
Codex, Claude Code, Claude Desktop, Cursor and VS Code.
Is Google Contacts MCP free?
Yes. Google Contacts MCP is open source, so you can use and self-host it for free.
How do I add Google Contacts MCP to Claude Code?
Run this command in your terminal: claude mcp add mcp-google-contacts --env GOOGLE_CONTACTS_CLIENT_SECRET='<GOOGLE_CONTACTS_CLIENT_SECRET>' --env GOOGLE_CONTACTS_REFRESH_TOKEN='<GOOGLE_CONTACTS_REFRESH_TOKEN>' --env GOOGLE_CONTACTS_ACCESS_TOKEN='<GOOGLE_CONTACTS_ACCESS_TOKEN>' -- npx -y mcp-google-contacts
What are the best alternatives to Google Contacts MCP?
The closest alternatives to Google Contacts MCP are TrendRadar, Ha MCP, Concord MCP, Getmitra and note1.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.

