google-contacts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Google Contacts

Independent, unofficial connector for Google Contacts. Not affiliated with, endorsed by, or sponsored by Google Contacts. "Google Contacts" is a trademark of its owner, used only to identify the service this connector works with.

Agent-callable tools for Google Contacts, wrapping the Google People API. Create, read, update, and delete a person's contacts; search contacts by name, email, or phone; set or remove contact photos; create and manage contact groups (labels) and their membership; and browse the auto-saved "other contacts" surface. Every tool uses a single OAuth connection; capability is gated by the granted scope.

独立的非官方Google Contacts连接器。与Google Contacts无关联、未获其认可或赞助。"Google Contacts"是其所有者的商标，仅用于标识本连接器所适配的服务。

可由Agent调用的Google Contacts工具，封装了Google People API。支持创建、读取、更新和删除个人联系人；按姓名、邮箱或电话搜索联系人；设置或移除联系人照片；创建和管理联系人组（标签）及其成员；浏览自动保存的“其他联系人”模块。所有工具均使用单一OAuth连接，功能权限由授予的范围决定。

When to use this

适用场景

Saving, finding, updating, or deleting a person's Google Contacts ("add Jane to my contacts", "what's Bob's email", "remove this contact").
Organizing contacts into groups/labels and adding or removing members.
Setting or removing a contact's photo.
Finding someone the user has interacted with (e.g. emailed) but never explicitly saved — the "other contacts" surface — and promoting them into saved contacts.

保存、查找、更新或删除个人Google Contacts（例如“把Jane添加到我的联系人”“Bob的邮箱是什么”“删除这个联系人”）。
将联系人整理到组/标签中，添加或移除成员。
设置或移除联系人照片。
查找用户曾互动过（例如通过邮件）但未明确保存的联系人——即“其他联系人”模块，并将其转为已保存联系人。

Setup

设置步骤

This is an agentskills.io skill.

If the connector has not been installed as a skill yet, install it first with

npx skills add zapier/connectors --skill google-contacts

(or your harness's own skill-install mechanism), then continue here.

The connector runs on Node.js 22.18+. Pick the reference that matches how you're running it, and load it before doing anything else:

You have...	Load
An MCP-aware client — tools may already be loaded (e.g. `mcp__google-contacts__<tool>` ), or you can register a local server yourself (or guide the user to)	`references/use-as-mcp.md`
Terminal / subprocess access (you can run `node` )	`references/use-as-cli.md`
Only your own code, importing this package as a dependency	`references/use-as-sdk.md`

这是一款agentskills.io skill。

如果该连接器尚未作为skill安装，请先使用

npx skills add zapier/connectors --skill google-contacts

（或你的工具链自带的skill安装机制）进行安装，然后继续以下操作。

该连接器运行于**Node.js 22.18+**环境。根据你的运行方式选择对应的参考文档，并在操作前加载：

你的环境...	加载方式
支持MCP的客户端——工具可能已加载（例如 `mcp__google-contacts__<tool>` ），你也可以自行注册本地服务器（或引导用户注册）	`references/use-as-mcp.md`
具备终端/子进程访问权限（可运行 `node` ）	`references/use-as-cli.md`
仅使用自有代码，将此包作为依赖导入	`references/use-as-sdk.md`

Scripts

脚本

All scripts use the single

google-contacts

connection.

Script	Script name	Connections	Description
`scripts/createContact.ts`	`createContact`	`google-contacts`	Create a contact from structured name, email, phone, address, and organization fields.
`scripts/getContact.ts`	`getContact`	`google-contacts`	Retrieve a single contact by resource name, with full field detail.
`scripts/updateContact.ts`	`updateContact`	`google-contacts`	Update a contact; each array sent replaces that whole field, omitted fields are untouched.
`scripts/deleteContact.ts`	`deleteContact`	`google-contacts`	Delete a contact from the account.
`scripts/listContacts.ts`	`listContacts`	`google-contacts`	List the account's contacts, paginated — the primary resourceName resolver.
`scripts/searchContacts.ts`	`searchContacts`	`google-contacts`	Search contacts by name, nickname, email, phone, or organization (prefix match).
`scripts/updateContactPhoto.ts`	`updateContactPhoto`	`google-contacts`	Set or replace a contact's photo from a base64-encoded image.
`scripts/deleteContactPhoto.ts`	`deleteContactPhoto`	`google-contacts`	Remove a contact's photo, reverting to the default avatar.
`scripts/listContactGroups.ts`	`listContactGroups`	`google-contacts`	List contact groups (labels), user and system — the contactGroupResourceName resolver.
`scripts/getContactGroup.ts`	`getContactGroup`	`google-contacts`	Get a single contact group, optionally with its member contact resource names.
`scripts/createContactGroup.ts`	`createContactGroup`	`google-contacts`	Create a new user contact group (label).
`scripts/updateContactGroup.ts`	`updateContactGroup`	`google-contacts`	Rename a user contact group (system groups cannot be renamed).
`scripts/deleteContactGroup.ts`	`deleteContactGroup`	`google-contacts`	Delete a user contact group (label), optionally with its member contacts.
`scripts/modifyContactGroupMembers.ts`	`modifyContactGroupMembers`	`google-contacts`	Add and/or remove contacts in a group without disturbing other memberships.
`scripts/listOtherContacts.ts`	`listOtherContacts`	`google-contacts`	List auto-saved "other contacts" (people interacted with but never saved).
`scripts/searchOtherContacts.ts`	`searchOtherContacts`	`google-contacts`	Search "other contacts" by name, email, or phone (prefix match).
`scripts/copyOtherContact.ts`	`copyOtherContact`	`google-contacts`	Promote an "other contact" into saved contacts, returning an editable contact.

所有脚本均使用单一

google-contacts

连接。

脚本	脚本名称	连接名称	描述
`scripts/createContact.ts`	`createContact`	`google-contacts`	根据结构化的姓名、邮箱、电话、地址和组织字段创建联系人。
`scripts/getContact.ts`	`getContact`	`google-contacts`	通过资源名称检索单个联系人，包含完整字段详情。
`scripts/updateContact.ts`	`updateContact`	`google-contacts`	更新联系人；传入的每个数组会替换对应字段的全部内容，未传入的字段保持不变。
`scripts/deleteContact.ts`	`deleteContact`	`google-contacts`	从账户中删除联系人。
`scripts/listContacts.ts`	`listContacts`	`google-contacts`	分页列出账户中的联系人——主要的resourceName解析器。
`scripts/searchContacts.ts`	`searchContacts`	`google-contacts`	按姓名、昵称、邮箱、电话或组织（前缀匹配）搜索联系人。
`scripts/updateContactPhoto.ts`	`updateContactPhoto`	`google-contacts`	通过Base64编码的图片设置或替换联系人照片。
`scripts/deleteContactPhoto.ts`	`deleteContactPhoto`	`google-contacts`	移除联系人照片，恢复为默认头像。
`scripts/listContactGroups.ts`	`listContactGroups`	`google-contacts`	列出联系人组（标签），包括用户自定义和系统默认组——contactGroupResourceName解析器。
`scripts/getContactGroup.ts`	`getContactGroup`	`google-contacts`	获取单个联系人组，可选择包含其成员联系人的资源名称。
`scripts/createContactGroup.ts`	`createContactGroup`	`google-contacts`	创建新的用户自定义联系人组（标签）。
`scripts/updateContactGroup.ts`	`updateContactGroup`	`google-contacts`	重命名用户自定义联系人组（系统组无法重命名）。
`scripts/deleteContactGroup.ts`	`deleteContactGroup`	`google-contacts`	删除用户自定义联系人组（标签），可选择同时删除其成员联系人。
`scripts/modifyContactGroupMembers.ts`	`modifyContactGroupMembers`	`google-contacts`	在组中添加和/或移除联系人，不影响其他成员关系。
`scripts/listOtherContacts.ts`	`listOtherContacts`	`google-contacts`	列出自动保存的“其他联系人”（曾互动但未保存的联系人）。
`scripts/searchOtherContacts.ts`	`searchOtherContacts`	`google-contacts`	按姓名、邮箱或电话（前缀匹配）搜索“其他联系人”。
`scripts/copyOtherContact.ts`	`copyOtherContact`	`google-contacts`	将“其他联系人”转为已保存联系人，返回可编辑的联系人信息。

Auth

认证

Every shape passes auth as one connection selector, not the secret — a

[<resolver>:]<value>

string. Every connector accepts

zapier:<connection-id>

(Zapier-managed auth — routes through Zapier's auth, retries, and governance layer); some also accept one or more direct-token resolvers (naming and count vary per connector) — check this connector's own resolvers rather than assuming. The

<resolver>:

prefix is optional; a bare value goes to the first resolver that claims it. Each script declares the connections it needs and the resolvers each accepts. The exact syntax for passing a connection (and how to see this connector's resolver list) differs by shape — see the reference you loaded above.

Google Contacts uses OAuth 2.0. The connector needs Google "contacts" access (read/write); the other-contacts tools additionally need "other contacts" read access. On a

, reconnect with contacts access granted.

zapier:<connection-id>
(recommended) — route through a Zapier-managed Google Contacts connection (
```
GOOGLE_CONTACTS_ZAPIER_CONNECTION_ID
```
); Zapier holds the OAuth credential and refreshes it automatically. Find the id with
```
npx zapier-sdk list-connections GoogleContactsCLIAPI
```
.
env:GOOGLE_CONTACTS_ACCESS_TOKEN
(direct) — a Google OAuth access token sent as a bearer. Good for short-lived/testing use: Google access tokens expire ~1 hour after issue and this path does not refresh them, so the Zapier-managed connection is the durable choice.

所有操作均通过单个连接选择器传递认证信息，而非密钥——格式为

[<resolver>:]<value>

的字符串。所有连接器均支持

zapier:<connection-id>

（由Zapier管理的认证——通过Zapier的认证、重试和治理层路由）；部分连接器还支持一种或多种直接令牌解析器（名称和数量因连接器而异）——请查看本连接器的专属解析器，不要假设通用。

<resolver>:

前缀为可选；若仅传入值，则会交由第一个匹配的解析器处理。每个脚本都会声明所需的连接及支持的解析器。传递连接的具体语法（以及查看本连接器解析器列表的方式）因环境而异——请参考你之前加载的文档。

Google Contacts采用OAuth 2.0认证。连接器需要Google的“联系人”访问权限（读写）；“其他联系人”工具还需要“其他联系人”的读取权限。若返回

错误，请重新连接并授予联系人访问权限。

zapier:<connection-id>
(推荐) —— 通过Zapier管理的Google Contacts连接（
```
GOOGLE_CONTACTS_ZAPIER_CONNECTION_ID
```
）路由；Zapier会保存OAuth凭证并自动刷新。可通过
```
npx zapier-sdk list-connections GoogleContactsCLIAPI
```
获取连接ID。
env:GOOGLE_CONTACTS_ACCESS_TOKEN
(直接模式) —— 作为Bearer令牌发送的Google OAuth访问令牌。适用于短期/测试场景：Google访问令牌在颁发后约1小时过期，且此方式不会自动刷新令牌，因此Zapier管理的连接是更持久的选择。

Output format

输出格式

Every script returns a

{ data, meta }

envelope:

data
— the script's result (the shape its
```
outputSchema
```
declares; see the reference you loaded above for how to inspect a script's exact schema in your shape).
meta.outputDataValidation
— what validating
```
data
```
did:
- ```
{ skipped: false, droppedPaths: null }
```
  — validated, nothing removed.
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  — validated, but those paths were stripped from
```
data
```
  : fields the script returned from the API that the
```
outputSchema
```
  doesn't declare. If you need them, re-run with output validation skipped.
- ```
{ skipped: true }
```
  — validation was bypassed;
```
data
```
  is the raw, unchecked script output.

Reading dropped fields /
skipOutputDataValidation
. To receive the raw, unvalidated result, opt out of output validation (the exact syntax differs by shape — see the reference you loaded above). Input validation is never skipped.

Trimming the result /
filterOutputData
. To shrink a large result down to the fields you need, pass a jq expression that post-processes

data

(again, exact syntax per shape). The jq runs against

data

only, NOT the

{ data, meta }

envelope, so write it rooted at

data

(run the script's

--help

— or your shape's equivalent — to see its output schema). The transformed value replaces

data

meta

is preserved, and the result is NOT re-validated against the output schema.

每个脚本都会返回一个

{ data, meta }

结构：

data
—— 脚本的执行结果（其
```
outputSchema
```
定义的结构；请参考你加载的文档，了解如何在你的环境中查看脚本的具体输出 schema）。
meta.outputDataValidation
—— 对
```
data
```
的验证结果：
- ```
{ skipped: false, droppedPaths: null }
```
  —— 已验证，未移除任何内容。
- ```
{ skipped: false, droppedPaths: [...], instruction }
```
  —— 已验证，但这些路径已从
```
data
```
  中移除：脚本从API返回的字段未在
```
outputSchema
```
  中声明。若需要这些字段，请跳过输出验证后重新运行。
- ```
{ skipped: true }
```
  —— 已绕过验证；
```
data
```
  为原始的、未经过检查的脚本输出。

读取被丢弃的字段 /
skipOutputDataValidation
。若要接收原始的未验证结果，请禁用输出验证（具体语法因环境而异——请参考你加载的文档）。输入验证永远不会被跳过。

精简结果 /
filterOutputData
。若要将大型结果精简为你需要的字段，请传入一个jq表达式对

data

进行后处理（同样，具体语法因环境而异）。jq仅针对

data

运行，而非

{ data, meta }

结构，因此表达式需以

data

为根（运行脚本的

--help

命令——或你的环境中的等效命令——查看其输出schema）。转换后的值将替换

data

，

meta

保持不变，且结果不会重新根据输出schema进行验证。

Disambiguation & refusals

歧义处理与拒绝规则

Resolve names before writing. Before
```
updateContact
```
/
```
deleteContact
```
/
```
modifyContactGroupMembers
```
on a contact identified by name, call
```
searchContacts
```
(or
```
listContacts
```
) and count exact, case-insensitive name matches. One match → act on it; don't over-ask. Two or more that tie → stop, list the candidates with a distinguishing field (email or phone), and ask which one — never silently pick. The same rule applies to groups via
```
listContactGroups
```
.
Editing a list field replaces it.
```
updateContact
```
replaces each array you send (e.g.
```
emailAddresses
```
) wholesale. To add a value without dropping the others,
```
getContact
```
first, append, then send the full array. For group membership, prefer
```
modifyContactGroupMembers
```
(element-level) over
```
updateContact
```
.
Out of scope — decline, don't substitute. This connector does not do bulk/batch contact create-update-delete, Google Workspace directory lookups, or contact merge/dedupe. If asked for one of these, say it isn't supported and stop — do not call another tool and report it as done.
No bulk operations — never loop to fake one. There is no batch endpoint. If asked to change, add, or delete a field across many or all contacts at once (e.g. "set everyone's company to Acme"), decline and explain it isn't supported — do not loop
```
updateContact
```
/
```
deleteContact
```
/
```
modifyContactGroupMembers
```
over multiple contacts to simulate a bulk operation. Acting on a single, explicitly-identified contact is fine; fanning out across the address book is not.

写入前解析名称。在对通过姓名标识的联系人执行
```
updateContact
```
/
```
deleteContact
```
/
```
modifyContactGroupMembers
```
操作前，请调用
```
searchContacts
```
（或
```
listContacts
```
）并统计完全匹配（不区分大小写）的姓名结果。若仅有一个匹配项，则执行操作；无需额外询问。若有两个或多个匹配项，则停止操作，列出带有区分字段（邮箱或电话）的候选者，并询问用户选择哪一个——切勿静默选择。此规则同样适用于通过
```
listContactGroups
```
处理组的场景。
编辑列表字段会替换整个字段。
```
updateContact
```
会完全替换你传入的每个数组（例如
```
emailAddresses
```
）。若要在不删除原有值的情况下添加新值，请先调用
```
getContact
```
，追加新值，然后发送完整数组。对于组成员管理，优先使用
```
modifyContactGroupMembers
```
（元素级操作）而非
```
updateContact
```
。
超出范围的请求——拒绝，不要替代。本连接器不支持批量创建/更新/删除联系人、Google Workspace目录查询或联系人合并/去重。若收到此类请求，请告知用户不支持该功能并停止操作——切勿调用其他工具并谎称已完成。
不支持批量操作——切勿通过循环模拟。本连接器无批量端点。若用户要求一次性修改、添加或删除多个或全部联系人的某个字段（例如“将所有人的公司设置为Acme”），请拒绝并说明不支持该功能——切勿通过循环调用
```
updateContact
```
/
```
deleteContact
```
/
```
modifyContactGroupMembers
```
来模拟批量操作。对单个明确标识的联系人执行操作是允许的；但遍历整个通讯录进行操作是不允许的。

References

参考文档

Load the matching reference file before working in that area:

Reference	Covers	Load it when
`references/google-contacts-api-gotchas.md`	Error codes, update replacement semantics, etag concurrency, search prefix matching + warmup, write propagation delay, resource name formats, contact group types, membership limits, other-contacts field restrictions, and pagination.	Before any tool call.

在对应场景下工作前，请加载匹配的参考文档：

参考文档	涵盖内容	加载时机
`references/google-contacts-api-gotchas.md`	错误代码、更新替换语义、etag并发、搜索前缀匹配与预热、写入传播延迟、资源名称格式、联系人组类型、成员限制、其他联系人字段限制及分页。	调用任何工具前。