Google Contacts MCP

Google Contacts MCP

English | Русский

A1 Google Contacts MCP 可让 AI 应用用日常语言管理你的 Google 通讯录。查找联系人、创建或更新联系人、用标签整理联系人、批量导入和清理联系人，还能将自动保存的“其他联系人”转为正式联系人。

它通过你的 Google 账号使用 Google Contacts 背后的 API——Google People API。每次更新都会进行并发编辑保护，通过明确的字段掩码精简读取内容，并清晰说明 People API 的限制，而不会暗示所有联系人操作都能实现。

• 25 个工具。 列出、搜索和读取联系人，逐个或批量创建、更新和删除联系人，管理联系人群组及成员关系，并访问“其他联系人”。
• 在对话中连接。 说“连接 Google Contacts”：服务会引导你完成 OAuth 客户端设置，通过 PKCE 在 127.0.0.1 捕获 Google 的重定向，并自行保管令牌——无需配置文件，也无需重启。
• 更新不会覆盖并发修改。 每次更新都受 etag 保护：如果联系人在读取后已在其他位置发生变化，写入会失败，而不会悄悄覆盖并发修改。
• 删除会永久生效。 People API 没有回收站；删除联系人或群组无法撤销，服务会将这些工具标记为破坏性操作，以便 AI 应用先征求确认。
• 仅需最少的 Google 权限范围。 读写使用 contacts——只读配置使用 contacts.readonly 即可——只有访问“其他联系人”时才需要 contacts.other.readonly，无需广泛的账号访问权限。

先从只读问题开始：

找出我通讯录中所有来自 Acme 的联系人，并显示他们的电子邮件地址和电话号码。

连接服务 · 探索使用场景 · 查看技术文档

一分钟了解它的工作方式

你： 显示 Jane Doe 的联系人卡片——电子邮件、电话和公司。

助手： 查找该联系人并显示所需字段。不会进行任何更改。

你： 将她的电话号码改为 +1 415 555 0100，并将她添加到“客户”标签。

助手： 显示联系人和拟议的更改，然后在写入前请求确认。

你： 确认。

助手： 应用受 etag 保护的更新并添加标签。如果期间联系人在其他位置发生了变化，写入会失败，而不会覆盖现有修改。

目录

• 快速开始
• 你可以让它做什么
• 联系人如何变更
• 可以更改哪些内容
• 获取访问权限
• 配置
• 数据、限制和后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+ 和一个 Google 账号。安装时不需要凭据——服务会在对话中连接。

1. 将服务添加到你的 AI 应用。
2. 说“连接 Google Contacts”：助手会引导你创建 OAuth 客户端并批准访问权限，无需编辑配置文件。
3. 提出上面的只读问题。

codex mcp add google-contacts \
  -- npx -y mcp-google-contacts@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-contacts \
  -- npx -y mcp-google-contacts@latest

claude mcp list

{
  "mcpServers": {
    "google-contacts": {
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-contacts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

{
  "servers": {
    "google-contacts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

你可以让它做什么

查找和查看联系人

• 查找所有来自 Acme 的联系人，并显示他们的邮箱和电话号码。
• 显示“Clients”标签中的联系人。
• 列出上次同步后发生变更的联系人。

保持通讯录为最新状态

• 为 Jane Doe 创建联系人，并填写她的邮箱、电话和公司。
• 更新联系人的电话号码或职位名称。
• 一次批量导入 50 个人，或通过一次调用删除过时的联系人。

使用标签整理

• 创建“Clients”标签并将这些联系人添加到其中。
• 重命名标签，或将联系人从一个标签移到另一个标签。
• 删除标签但保留其中的联系人——也可以连同联系人一起删除，但只有在明确要求时才会这样做。

使用“其他联系人”

• 显示 Google 自动保存的、未保存在我的联系人的地址。
• 将其中一个复制到“我的联系人”，作为正式联系人。

联系人如何变化

1. 每个联系人、群组和其他联系人都有一个完整的资源名称（people/c...、contactGroups/...、otherContacts/...）；工具通过该名称定位记录，与 API 返回的名称完全一致。
2. 读取操作只返回字段掩码中指定的字段（默认包括姓名、电子邮件、电话、组织和群组成员关系）。字段缺失可能只是因为它不在掩码中，而非内容为空。
3. 更新会将每个提供的字段组作为整体替换，并受 etag 保护：如果联系人在读取后于其他位置发生了变化，写入就会失败，而不会覆盖并发修改。
4. 删除不可撤销。People API 没有回收站，也无法撤销。

搜索会查询可能滞后最近写入几秒的缓存，最多返回 30 条结果。“其他联系人”——Google 自动保存的地址——只能读取或复制到“我的联系人”，不能直接编辑。没有专用工具可管理联系人照片；raw_request 可以调用这些端点。

可以进行的更改

AI 客户端控制确认提示。服务会标记读取、写入和具有破坏性的工具，以便客户端区分检查操作与实际更改。

获取访问权限

Google Contacts 需要 OAuth 2.0；仅有 API 密钥不够。有两种接入方式，第一种无需配置文件。

从聊天中连接（推荐）

说“连接 Google Contacts”，助手就会引导你完成整个流程：

1. setup_instructions 会显示检查清单：创建或选择 Google Cloud 项目、启用 Google People API、配置授权同意屏幕，并创建 桌面应用 OAuth 客户端。
2. 下载该客户端的 JSON（“Download JSON”），并将其路径提供给助手——set_client 会将其保存为仅所有者可访问。密钥不会经过对话传输。
3. start_login 会返回 Google 授权链接。在这台机器上打开链接并批准；验证码会通过一次性监听器返回到 127.0.0.1（PKCE），绝不会经过聊天传输。
4. finish_login 会交换验证码，并将令牌保存到 ~/.config/mcp-google-contacts/credentials.json（模式 0600），再通过真实的 Google People API 调用验证令牌——如果 API 仍处于关闭状态，就会在此时发现。

每次调用都会重新读取令牌，因此连接会立即生效，无需重启 AI 应用。auth_status 会显示当前连接状态；logout 会撤销并删除凭据。

环境变量（CI、无人值守安装）

1. 创建或选择一个 Google Cloud 项目，并启用 People API。

2. 配置 OAuth 同意屏幕，并创建 Desktop app OAuth 客户端。

3. 授权要管理其联系人的 Google 账号。启用 Use your own OAuth credentials 后，可通过 OAuth 2.0 Playground 获取刷新令牌。

4. 根据使用需求请求最小范围：

   https://www.googleapis.com/auth/contacts
   https://www.googleapis.com/auth/contacts.other.readonly
   

contacts 涵盖联系人和群组的读取与写入；对于只读设置，仅需 contacts.readonly。只有使用“Other contacts”工具时才需要 contacts.other.readonly。如果单个工具返回 403，通常意味着刷新令牌生成时未包含该工具所需的范围——添加缺少的范围后重新授权。

测试模式下的 OAuth 刷新令牌可能在七天后过期。如需长期访问，请发布 OAuth 应用，或在 Workspace 域中使用 Internal 应用。请将客户端密钥和刷新令牌视为密码。

配置

所有变量均为可选项——如果不设置任何变量，服务会从聊天中连接。

* 请提供 OAuth 三项凭据或访问令牌。即使完全没有凭据，服务仍会启动并完成 MCP 握手；首次调用工具时会指出需要设置的确切变量。

数据、限制和后台工作

• 请求会发送到 Google。 本地服务会刷新 Google OAuth 令牌，并调用 people.googleapis.com 上的 People API。匿名遥测包含安装 ID、软件包版本、AI 客户端和平台版本，以及工具名称——绝不包含 OAuth 令牌、联系人数据、工具参数或提示词。设置 ASKADS_TELEMETRY=0 即可选择退出。
• Google 配额按用户计算且额度较低。 默认 People API 配额允许每位用户每分钟大约进行 90 次读取和 90 次写入，因此批处理工具比循环进行单次调用更高效；修改数据的批处理必须一次运行一个。遇到 429 时，服务会退避并重试；读取操作遇到网络和 5xx 错误时也会重试，而写入操作在发生不确定故障后不会重放。
• 没有后台轮询。 服务仅在被调用时运行。list_contacts 支持同步令牌，因此，具有计划任务的 AI 应用可以定期只获取发生变化的内容；同步令牌约七天后过期，届时需要重新完整列出联系人。

技术文档

• MCP 能力目录 — 面向任务的页面，涵盖每个工具。
• 所有工具和输入
• 开发文档
• 发布文档
• Google People API 参考文档

支持

发现 Bug 或有使用场景需求？创建 issue或在 Telegram 上留言。

你已经读到最后了！