Connect Google Contacts to Claude: Sync Directory and Profile Details

If your team needs to connect Google Contacts to Claude to automate directory management, sync customer details across your organization, or clean up fragmented address books, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's JSON-RPC tool calls and the underlying Google People API. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Google Contacts to ChatGPT or explore our broader architectural overview on connecting Google Contacts to AI agents.

Giving a Large Language Model (LLM) read and write access to a sprawling ecosystem like Google Workspace is an engineering challenge. You have to handle Google's strict OAuth 2.0 token lifecycles, map massive nested JSON schemas to MCP tool definitions, and deal with the highly specific quirks of the People API. Every time Google updates an endpoint or deprecates a legacy Contact resource, you have to update your server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Google Contacts, connect it natively to Claude Desktop, and execute complex workflows using natural language.

The Engineering Reality of the Google Contacts API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against Google's People API is painful. You are not dealing with standard RESTful CRUD operations - you are dealing with a heavily optimized, highly nested data model designed for Google's internal scale.

If you decide to build a custom MCP server for Google Contacts, here are the specific integration challenges you will face:

The Tyranny of the readMask Unlike most APIs that return a standard set of fields by default, the Google People API requires a readMask parameter for almost every GET and LIST operation. If you do not explicitly state which fields you want (e.g., names,emailAddresses,phoneNumbers), the API will return a 200 OK with an empty object. You cannot simply tell an LLM to "get this contact" - the MCP tool schema must force the model to provide a valid comma-separated string of requested fields, or the server must inject a default readMask before proxying the request to Google.

Highly Nested, Array-Based Properties In Google Contacts, a person does not have a flat email or phone string field. Every attribute is an array of objects to account for multiple entries (work, home, primary). For example, to get a user's name, you must traverse names [0].displayName. An LLM trying to update a contact cannot just send {"email": "john@example.com"}. It must send a complex JSON structure targeting the specific metadata ID of the exact array item it wishes to mutate. Designing an MCP tool schema that reliably guides an LLM to format this payload correctly is incredibly difficult.

Strict Sequential Mutation Requirements Google explicitly states that mutate requests (updates and deletes) must be sent sequentially. If an AI agent attempts to run bulk deletions or updates by firing concurrent promises, the Google People API will throw latency spikes and 409 Conflict or 429 Too Many Requests errors. Your MCP server must either enforce a queueing mechanism or your LLM instructions must aggressively enforce sequential tool calling.

Generating a Managed MCP Server for Google Contacts

Instead of building a server from scratch to handle Google's OAuth flows and readMask intricacies, you can use Truto to generate a managed MCP server. This server dynamically exposes Google Contacts endpoints as MCP-compatible tools based on the active connection's resources.

Truto scopes every MCP server to a single integrated account (a specific tenant's connected Google account). The generated URL contains a secure, cryptographically hashed token that fully authenticates requests.

There are two ways to generate this server.

Method 1: Via the Truto UI

This is the fastest method for internal tooling or manual testing.

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Select the specific Google Contacts connection you want the LLM to access.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your desired configuration (e.g., name the server, filter to read methods only, set an expiration date).
6. Copy the generated MCP server URL. (You will only see this URL once).

Method 2: Via the Truto API

For production workflows, you should programmatically generate MCP servers when provisioning AI agents for your users. You can do this by making a POST request to the Truto API.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Claude_Google_Contacts_Access",
    "config": {
      "methods": ["read", "write"]
    },
    "expires_at": "2026-12-31T23:59:59Z"
  }'

The response will contain the authenticated URL needed to configure Claude:

{
  "id": "mcp_token_abc123",
  "name": "Claude_Google_Contacts_Access",
  "expires_at": "2026-12-31T23:59:59.000Z",
  "url": "https://api.truto.one/mcp/t_xyz987..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP server URL, you must register it with your AI client so the model can discover the available Google Contacts tools via the tools/list JSON-RPC handshake.

Method A: Via the Claude UI (Desktop/Web)

If you are using Claude Desktop (or the ChatGPT web interface if you have Developer mode enabled), you can add the server directly through the settings panel.

1. Open Claude Desktop.
2. Navigate to Settings -> Integrations (or Connectors in some versions).
3. Click Add MCP Server.
4. Paste the url you generated from Truto.
5. Click Add.

Claude will immediately ping the endpoint, execute the handshake, and cache the available tools.

Method B: Via the Manual Configuration File

For headless deployments, CI/CD environments, or strict local configurations, you can define the MCP server using Claude's standard claude_desktop_config.json file.

Since Truto exposes the server over Server-Sent Events (SSE) and HTTP POST, you use the official @modelcontextprotocol/server-sse proxy package to bridge the connection.

Add the following to your claude_desktop_config.json file:

{
  "mcpServers": {
    "google_contacts": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/t_xyz987..."
      ]
    }
  }
}

Restart Claude Desktop. The next time you open a chat, the model will have full access to the Google Contacts tools.

sequenceDiagram
    participant Claude as Claude Desktop
    participant Proxy as npx server-sse
    participant Truto as Truto MCP Router
    participant Google as Google People API

    Claude->>Proxy: tools/list (JSON-RPC)
    Proxy->>Truto: POST /mcp/t_xyz987
    Truto-->>Proxy: Returns auto-generated tools
    Proxy-->>Claude: Tools loaded in context
    
    Claude->>Proxy: tools/call (list_all_people)
    Proxy->>Truto: POST /mcp/t_xyz987
    Truto->>Google: GET /v1/people/connections
    Google-->>Truto: JSON payload
    Truto-->>Proxy: MCP Result (JSON string)
    Proxy-->>Claude: Formatted context

Hero Tools for Google Contacts Automation

Truto automatically derives tool schemas from the underlying integration documentation. The following are the highest-leverage tools available for Google Contacts automation.

list_all_people_search_contacts

This tool allows the LLM to execute text-based queries against a user's address book. Because of Google's architecture, the LLM must supply a query and a readMask (e.g., names,emailAddresses,phoneNumbers,organizations). Without the readMask, the returned records will be empty.

"Search my Google Contacts for anyone at 'Acme Corp'. Make sure you include their names, emailAddresses, and organizations in the readMask so I can see their titles."

get_single_people_search_contact_by_id

Fetches the complete profile details for a specific contact. The id parameter must follow the standard Google resource name format, typically starting with people/ (e.g., people/c123456789). The model must again specify the personFields parameter to dictate which arrays to return.

"Get the full profile details for contact ID people/c987654321. I need to see their phoneNumbers, emailAddresses, and userDefined custom fields to check their account status."

delete_a_people_search_contact_by_id

Deletes a contact record permanently from the directory. The LLM must pass the resource ID. Because of Google's strict latency and concurrency rules, mutating operations must be executed sequentially. The response is empty if successful.

"I need to clean up my address book. Delete the contact record for John Doe (ID: people/c112233). Do not attempt to delete any other records at the same time."

list_all_people_other_contacts

Google differentiates between "My Contacts" (explicitly saved contacts) and "Other Contacts" (people the user has interacted with, like emailing them, who are not saved in the primary address book). This tool is critical for auditing auto-saved interactions or promoting "Other Contacts" into the CRM.

"Search my 'Other Contacts' for anyone with an @stripe.com email address. I want to see if I've emailed anyone there recently who isn't saved in my main address book."

list_all_people

Lists people from the Google domain directory. This is distinct from personal contacts; it queries the global active directory for the Google Workspace organization. This is the primary tool used by IT admins to audit internal employee lists.

"List all people in our Google domain directory. I need to audit current employees to cross-reference against our HR system."

list_all_oauth_user_info

Retrieves the basic profile information about the currently authenticated Google user. The LLM uses this tool to gain context on "who" it is operating as, retrieving the user's unique identifier (sub), full name, and primary email address.

"Before we start modifying contacts, call the oauth_user_info tool to verify which Google account I am currently authenticated as."

For the complete tool inventory and detailed JSON Schema mappings, view the Google Contacts integration page.

Workflows in Action

When Claude is equipped with these tools, it can orchestrate complex, multi-step directory workflows autonomously.

Scenario 1: IT Offboarding and Directory Cleanup

IT administrators frequently need to remove terminated employees from shared organizational address books or audit the domain directory.

"Audit the Google domain directory for an employee named 'Sarah Jenkins'. If she exists, find her associated personal contact record in my address book and delete it so she no longer appears in my autocomplete."

Execution Steps:

1. Claude calls list_all_people with a search query for "Sarah Jenkins" to verify her presence in the global directory.
2. Claude calls list_all_people_search_contacts with query="Sarah Jenkins" and readMask="names,emailAddresses" to find her specific contact ID (e.g., people/c445566) in the user's personal address book.
3. Claude calls delete_a_people_search_contact_by_id passing id="people/c445566" to remove the record.

Result: The LLM successfully verifies the user and executes the cleanup operation, returning a confirmation message to the IT admin that the contact was removed.

flowchart TD
    A["User Prompt:<br>Audit and delete Sarah Jenkins"] --> B["Call tool:<br>list_all_people"]
    B --> C{"Found in directory?"}
    C -->|Yes| D["Call tool:<br>list_all_people_search_contacts"]
    C -->|No| E["Stop.<br>Report not found."]
    D --> F["Extract ID:<br>people/c445566"]
    F --> G["Call tool:<br>delete_a_people_search_contact_by_id"]
    G --> H["Return success to user"]

Scenario 2: Promoting Shadow Interactions to CRM

Sales Operations teams often need to find leads that reps have emailed but never officially saved in the CRM or their primary contacts list.

"Check my 'Other Contacts' for anyone matching 'Acme Corp'. If you find any, extract their email addresses and format them as a CSV list for me to import into our CRM."

Execution Steps:

1. Claude calls list_all_people_other_contacts using query="Acme Corp" and readMask="names,emailAddresses,organizations".
2. The API returns an array of auto-saved interaction records.
3. Claude parses the deeply nested JSON array (emailAddresses [0].value).
4. Claude aggregates the extracted data and formats it as a plain-text CSV block in the chat window.

Result: The sales operations manager receives a clean CSV of unlogged leads, skipping hours of manual address book exporting and deduplication.

Handling Google Contacts API Rate Limits

The Google People API enforces strict quota limits. The default limit is typically a set number of read/write requests per user per project per minute.

Important Note on Truto's Architecture: Truto does not automatically retry, throttle, or absorb rate limit errors. When the upstream Google API returns an HTTP 429 (Too Many Requests), Truto passes that error directly back to the caller (your Claude agent).

Truto normalizes the upstream rate limit information into standardized headers according to the IETF specification:

• ratelimit-limit: The total requests allowed in the current window.
• ratelimit-remaining: The number of requests remaining.
• ratelimit-reset: The time at which the window resets.

Your AI agent (or the client managing the LLM) is entirely responsible for reading these headers, implementing exponential backoff, and retrying the tool call once the reset window has passed.

Security and Access Control

Giving an AI agent access to an organization's directory data requires strict governance. Truto MCP servers support multiple layers of programmatic access control:

• Method Filtering: Restrict servers to specific operation types. Setting methods: ["read"] prevents the LLM from executing tools like delete_a_people_search_contact_by_id, effectively making the server read-only.
• Tag Filtering: Limit the server to specific resource tags. You can expose only the directory endpoints while hiding personal contacts endpoints.
• Extra Authentication (require_api_token_auth): When set to true, possessing the MCP URL is not enough. The client must also pass a valid Truto API token in the Authorization header, preventing unauthorized access if the URL leaks in logs.
• Time-to-Live (expires_at): Create ephemeral servers that automatically self-destruct. This is ideal for CI/CD pipelines or short-lived agentic tasks where standing access is a security risk.

Strategic Wrap-Up

Connecting Google Contacts to Claude via an MCP server turns a static address book into an active participant in your automated workflows. By abstracting away Google's OAuth requirements, nested array schemas, and complex readMask requirements, you allow your AI agents to do what they do best: reason over data and execute tasks.

Whether you are building internal tooling for IT admins or empowering sales teams to harvest unlogged leads, Truto provides the secure, declarative infrastructure to make it happen.