Google Contacts

Overview

Manage your Google Contacts: list, search, create, update, and delete contacts. Supports both simple flat-field input and canonical Google People API format for maximum flexibility.

Actions

list_contacts

List all contacts sorted by first name ascending.

Required fields: none (just the action)

Optional fields:

• page_size (integer, 1-200, default 25) - number of contacts per page
• page_token (string) - pagination token from a previous response

Example:

{
  "action": "list_contacts",
  "page_size": 50
}

Response includes: array of contacts (each with resource_name, etag, name, first_name, last_name, emails, phones, company, job_title, notes, addresses) and next_page_token if more results exist.

---

search_contacts

Search contacts by name, email, phone, or other text.

Required fields:

• query (string) - search text to match against contact fields

Optional fields:

• page_size (integer, 1-200, default 25)
• page_token (string)

Example:

{
  "action": "search_contacts",
  "query": "Jane Smith",
  "page_size": 10
}

---

get_contact

Retrieve a single contact by resource name.

Required fields:

• resource_name (string) - contact identifier, e.g. "people/c1234567890"

Example:

{
  "action": "get_contact",
  "resource_name": "people/c1234567890"
}

Note: You can pass the ID with or without the people/ prefix; it will be normalized automatically.

---

create_contact

Create a new contact. At least one field must be provided in the contact object.

Required fields:

• contact (object) - contact data with at least one field

Contact object fields (all optional, but at least one required):

• first_name (string) - given name
• last_name (string) - family name
• full_name (string) - display name (used to derive first/last if those are not provided; splits on spaces)
• email (string) - primary email address
• phone (string) - primary phone number
• company (string) - organization name
• job_title (string) - job title
• notes (string) - free-text notes
• address (object) - with fields: street_address, city, region, postal_code, country

Example:

{
  "action": "create_contact",
  "contact": {
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com",
    "phone": "+1-555-867-5309",
    "company": "Acme Corp",
    "job_title": "VP of Engineering",
    "notes": "Met at the 2026 tech conference",
    "address": {
      "street_address": "123 Main St",
      "city": "San Francisco",
      "region": "CA",
      "postal_code": "94105",
      "country": "US"
    }
  }
}

Alternative input formats: The contact object also accepts canonical Google People API format (e.g. names, emailAddresses, phoneNumbers arrays) and plural aliases (emails, phones arrays). The first element of each array is used.

---

update_contact

Update an existing contact. Only the fields you include in the contact object will be modified; other fields remain unchanged.

Required fields:

• resource_name (string) - the contact to update, e.g. "people/c1234567890"
• contact (object) - fields to update (same structure as create_contact)

Optional fields:

• etag (string) - ETag for optimistic concurrency. If omitted, the tool fetches the current ETag automatically.

Example:

{
  "action": "update_contact",
  "resource_name": "people/c1234567890",
  "contact": {
    "job_title": "CTO",
    "company": "New Ventures Inc"
  }
}

Note: The update mask is automatically derived from the fields you provide. For example, providing email updates only the emailAddresses field on the contact.

---

delete_contact

Permanently delete a contact.

Required fields:

• resource_name (string) - the contact to delete, e.g. "people/c1234567890"

Example:

{
  "action": "delete_contact",
  "resource_name": "people/c1234567890"
}

Warning: This action is irreversible. The contact is permanently removed.

---

Common Workflows

1. Find and Update a Contact

Search for a contact, then update their information:

1. search_contacts with query: "Jane Smith" to find the contact
2. Note the resource_name from the result (e.g. "people/c1234567890")
3. update_contact with that resource_name and the fields to change

2. Export a Contact List

Retrieve all contacts with pagination:

1. list_contacts with page_size: 200 (maximum per page)
2. If next_page_token is returned, call list_contacts again with that page_token
3. Repeat until no next_page_token is returned

3. Add a New Contact and Verify

Create a contact and confirm it was saved:

1. create_contact with the contact details
2. Note the resource_name from the response
3. get_contact with that resource_name to verify all fields were saved correctly

Important Notes

• Pagination: Maximum page_size is 200. Default is 25. Use next_page_token to retrieve additional pages.
• Resource names: Contact identifiers look like "people/c1234567890". You can pass just the ID portion (e.g. "c1234567890") and it will be normalized.
• Name derivation: If you provide full_name without first_name/last_name, the tool splits on spaces: first word becomes given name, remaining words become family name.
• Update behavior: Only fields included in the contact object are updated. Omitted fields are not cleared.
• ETag handling: For updates, the ETag is fetched automatically if not provided. You can pass the etag from a previous get/list response for optimistic concurrency control.
• Single values only: The flat input format (email, phone) stores one value per field. If you need multiple emails or phones, use the People API array format (emailAddresses, phoneNumbers), though only the first entry in each array is used.
• Sorting: list_contacts always returns results sorted by first name ascending.
• Delete is permanent: There is no undo for delete_contact.