Google Contacts MCP

Shows whether this server is connected to Google: token presence and source (env variables or a stored in-chat login), expiry, the Google account email, granted vs missing OAuth scopes, where the credentials file lives and where the OAuth client comes from. Makes no network calls and never returns the token itself. Call it first when other tools report the server is not connected.

Takes no parameters.

Step-by-step checklist for connecting this server to Google: creating a Google Cloud project and a Desktop-app OAuth client, publishing the consent screen (mandatory — Testing-mode refresh tokens die after 7 days), downloading the client JSON and handing its PATH to set_client. Works without any credentials; the checklist shortens to 'enable the API + log in' when an OAuth client is already configured (one client serves the whole mcp-google-* line). Never asks the user to paste secrets into the chat.

Takes no parameters.

Saves the OAuth client credentials from the JSON file downloaded from Google Cloud Console ('Download JSON' on a Desktop-app client). Pass the file PATH — the secret must never be pasted into the chat. The client is stored once in the shared ~/.config/mcp-google-auth/client.json (owner-only) and reused by every mcp-google-* server; tokens stay per-server. After this, call start_login.

First step of connecting from the chat, without editing config files or restarting the client. Returns authorizeUrl — show it to the user as a clickable link and ask them to open it in the browser ON THIS MACHINE, pick the Google account and approve access. A one-shot listener on 127.0.0.1 catches Google's redirect; the code is exchanged locally and never passes through the chat. Does not open the browser itself. The attempt lives 10 minutes; when the browser shows the success page, call finish_login.

Takes no parameters.

Second step: waits up to 20 s for the browser consent to finish, saves the tokens to an owner-only file and verifies the login with a read-only identity call, returning the account email and the granted scopes. After success every tool works immediately — no client restart. If the user granted only part of the requested permissions, the login is still saved and missingScopes lists what will not work. Logging in under a different Google account replaces the previous login (its refresh token is revoked best-effort) and the response carries previousAccountEmail so the change never goes unnoticed.

Takes no parameters.

Revokes the stored token at Google (oauth2.googleapis.com/revoke) and deletes the local credentials file. Tokens supplied via env variables are NOT touched — remove them from the MCP client config manually; envTokenStillSet in the response says whether any are still in effect.

Takes no parameters.

Lists the account's saved contacts (People API people/me/connections): connections[] of Person objects with resourceName, etag and the requested person_fields (default names, emailAddresses, phoneNumbers, organizations, memberships — an absent field may be unmasked, not empty), plus nextPageToken, totalItems and (when requested) nextSyncToken. page_size up to 1000 (default 100); paginate with page_token. For incremental polling set request_sync_token=true on a full listing, store nextSyncToken, and pass it as sync_token next time to get only changed/deleted people (deleted ones carry metadata.deleted=true); an expired token (~7 days) fails with HTTP 410 EXPIRED_SYNC_TOKEN — re-list without sync_token. Covers only the user's own saved contacts — not the Workspace directory and not auto-saved addresses (see list_other_contacts).

Searches the account's saved contacts by prefix match on names, nicknames, emails, phones and organizations (People API people:searchContacts). Returns results[] of { person } with the requested read_mask fields. Max 30 results, no pagination — this is a quick lookup, not an export; use list_contacts to enumerate everything. The search index lags writes by seconds to minutes: a contact created or updated moments ago may be missing here even though list_contacts and get_contact already see it (the documented cache-warmup request is sent automatically before the session's first search, but the lag is server-side). Searches only the user's own saved contacts.

Fetches one contact by resource name ("people/c...", or "people/me" for the signed-in user's own profile) with an explicit field mask. Returns a Person with resourceName, etag and the requested person_fields (default names, emailAddresses, phoneNumbers, organizations, memberships). The etag in the result is what update_contact needs to change this contact safely; memberships list the contact's groups as contactGroups/<id> resource names.

Fetches up to 200 contacts in one call (People API people:batchGet) — far cheaper against the tight per-user quota than a get_contact loop. Returns responses[], one per requested resource name IN THE SAME ORDER, each { requestedResourceName, status, person }; a missing contact gets a NOT_FOUND status in its own entry instead of failing the whole call, so check per-entry status. person_fields works exactly like in get_contact.

Creates a new contact in the account's Google Contacts and returns the created Person (resourceName, etag and the person_fields mask — use the resourceName for every later call). Provide any subset of the normalized fields: name parts, nickname, emails[], phones[], addresses[], organization, birthday, notes, urls[]; at least one is required. The API has NO duplicate detection — creating the same contact twice yields two contacts, so after an ambiguous failure (timeout/5xx; never auto-retried) check via search/list before re-sending. A just-created contact appears in list_contacts/get_contact immediately but reaches the search_contacts index with a delay. Contact photos need raw_request (updateContactPhoto).

Updates an existing contact and returns the updated Person. Only the provided fields are touched (updatePersonFields is computed automatically), but each provided field group is REPLACED AS A WHOLE: passing emails replaces all emails ([] clears them), passing any name part rewrites the whole name, and scalar fields clear on an empty value ("" for nickname/notes/birthday, {} for organization) — fetch current values with get_contact first and send complete groups, or data is silently dropped. Updates are etag-guarded: pass the etag from get_contact to fail cleanly (HTTP 400) if someone edited the contact meanwhile, or omit it and the current etag is fetched automatically (one extra read; last-write-wins). At least one contact field is required.

Permanently deletes one contact from the account's Google Contacts. There is no undo through this API (the Google Contacts UI keeps its own 30-day trash, but nothing here reads or restores it) — verify the resource_name with get_contact before deleting. Returns an empty result on success. After an ambiguous failure (timeout/5xx; never auto-retried) check with get_contact before re-sending: the delete may already have happened, and a second attempt then fails with 404.

Lists the account's contact groups (labels): contactGroups[] with resourceName (contactGroups/<id>), name, groupType and memberCount, plus nextPageToken and totalItems. Two kinds come back: USER_CONTACT_GROUP (labels the user created — the only kind that can be renamed or deleted) and SYSTEM_CONTACT_GROUP (built-ins like contactGroups/myContacts and contactGroups/starred — fixed). group_fields defaults to metadata, groupType, memberCount, name; add memberCount explicitly if you narrow it and still want sizes. page_size up to 1000; sync_token works like in list_contacts (410 = expired, re-list in full).

Fetches one contact group by resource name: name, groupType, memberCount and etag — plus, when max_members > 0, memberResourceNames[] with up to that many member contacts as people/<id> resource names (the only way the API returns a group's members; feed them to batch_get_contacts for details). The etag is what update_contact_group uses to rename safely.

Creates a new user contact group (label) and returns it (resourceName contactGroups/<id>, name, etag). Group names must be unique — creating a duplicate name fails with 409 CONFLICT rather than making a second group. Put contacts into the new group with modify_group_members.

Renames a user contact group (the only mutable group attribute). Etag-guarded like contact updates: pass etag from get_contact_group to fail cleanly on a concurrent edit, or omit it and the current etag is fetched automatically (one extra read). System groups (contactGroups/myContacts, starred, ...) cannot be renamed; the new name must stay unique (409 CONFLICT otherwise). Returns the updated group.

Permanently deletes a user contact group (label). By default the member contacts SURVIVE — they only lose the label; delete_contacts=true also PERMANENTLY DELETES every contact in the group, so use it only when that is explicitly wanted (check the roster first via get_contact_group with max_members). System groups cannot be deleted. Returns an empty result on success; there is no undo through this API.

Adds and/or removes contacts in a contact group (label) in one call — at least one of add/remove is required, together up to ~1000 names. Contacts are addressed by their people/<id> resource names. The HTTP 200 response is NOT a full success receipt — read it: notFoundResourceNames lists contacts that do not exist (their changes were skipped) and canNotRemoveLastContactGroupResourceNames lists contacts that could not leave their last group. Removing a contact from a group never deletes the contact, and re-running the same call converges. Contacts cannot be removed from contactGroups/myContacts this way.

Creates up to 200 contacts in one call (People API people:batchCreateContacts). Each entry takes the same normalized fields as create_contact (name parts, emails[], phones[], addresses[], organization, birthday, notes, urls[]) and needs at least one. Returns createdPeople[] with each new resourceName. The call is atomic — a validation error anywhere creates nothing — but after an AMBIGUOUS failure (timeout/5xx; never auto-retried) the batch may still have committed: check via list_contacts before re-sending, or every contact gets created twice (the API has no duplicate detection). Send mutate batches sequentially, never in parallel — that is also how the per-user write quota stretches furthest.

Updates up to 200 contacts in one call (People API people:batchUpdateContacts). Each entry names a contact (resource_name, optional etag — missing etags are auto-fetched in ONE extra batchGet read) plus the same normalized fields as update_contact. CAUTION — the API applies ONE shared update mask to the whole batch, computed here as the union of every entry's provided field groups: a group that one entry provides and another omits is CLEARED on the omitting entry. Safest is to give every entry the same set of fields; each provided group replaces its stored group as a whole, exactly like update_contact. Atomic per request; a stale etag fails the whole batch with 400 — re-read and retry deliberately, never blindly.

Permanently deletes up to 500 contacts in one call (People API people:batchDeleteContacts). There is no undo through this API — list the exact resource names first (batch_get_contacts shows what each one is) and treat the call as final. Returns an empty result on success; atomic per request. After an ambiguous failure (timeout/5xx; never auto-retried) check which contacts still exist via batch_get_contacts instead of re-sending — the deletes may have committed, and a second call then reports NOT_FOUND.

Lists 'Other contacts' — addresses Google auto-saved from the user's email interactions; they are NOT in the saved contact list and never appear in list_contacts/search_contacts. Give query to search them instead of listing (prefix match, max 30 results, no pagination — the warmup request is sent automatically before the session's first search); without query it lists with page_token pagination (page_size up to 1000) and optional sync tokens (request_sync_token/sync_token; expired ones fail with 410 — re-list in full). Only names, emailAddresses, phoneNumbers, photos and metadata exist here. Other contacts are read-only: to edit one, first make it a real contact with copy_other_contact. Requires the contacts.other.readonly OAuth scope — a 403 means the refresh token was minted without it.

Copies an 'Other contact' (from list_other_contacts) into the user's saved contacts — the only write that exists for Other contacts. copy_mask picks which fields carry over (names, emailAddresses, phoneNumbers; default all three). Returns the NEW saved person — use its resourceName ('people/c...') for further edits; the original otherContacts entry remains. Copying the same entry twice creates duplicate saved contacts. Requires BOTH the contacts and contacts.other.readonly OAuth scopes.

Escape hatch to call any Google People API v1 path directly, for requests the typed tools don't cover — e.g. contact photos (PATCH "v1/people/<id>:updateContactPhoto" with {"photoBytes":"<base64>"} or DELETE "v1/people/<id>:deleteContactPhoto"), "Other contacts" (GET "v1/otherContacts?readMask=..." — needs the contacts.other.readonly scope on the token), or extra query parameters like sources. The path may carry a query string; repeated parameters are written inline ("v1/people:batchGet?resourceNames=people/a&resourceNames=people/b&personFields=names"). The Bearer token is added automatically; the method defaults to GET. Writes are never retried after ambiguous failures.