Google Contacts

google-contacts-mcp

用于 Google Contacts 的 MCP 服务——列出、搜索和管理联系人。

使用场景

查找邮箱：“看看最新收到的 JIRA 工单。我们能给安全团队的 Sarah 发邮件，征求她的意见吗？”→ 查找 Sarah 的邮箱并起草邮件。

录入名片：参加社交活动后，拍下名片照片 → 助手提取详细信息并将其添加为联系人，同时备注你们的相识地点。

查找人脉：“我在 Google 有哪些熟人？”或“我下周要去伦敦——该和谁叙叙旧？”→ 搜索你的个人社交网络。

通话提醒：“提醒我下午 3 点给 Mike 打电话”→ 创建日历事件并附上 Mike 的电话号码，这样你就能直接从提醒中拨打电话。

更新联系人：你收到一封自动回复，得知有人已离开公司并留下了新的个人邮箱 → 助手会自动更新其联系人信息。

（这些只是示例——任何需要查找或管理联系人的工作流都可以使用此工具。）

设置

1. 创建 Google OAuth 凭据

1. 前往 Google Cloud Console
2. 创建新项目（或使用现有项目）
3. 启用 People API
4. 前往 APIs & Services → OAuth consent screen，设置同意屏幕
5. 前往 APIs & Services → Credentials → Create Credentials → OAuth client ID
6. 选择 Web application
7. 将 http://localhost:3000/callback 添加到 Authorized redirect URIs
8. 记下 Client ID 和 Client Secret

2. 运行服务

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

服务默认运行在 http://localhost:3000。使用 PORT=3001 更改端口。

3. 添加到 MCP 客户端

服务运行后，按照 install-mcp 上的说明操作。该页面会为你的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Cline、VS Code 等）生成合适的配置。

架构

此服务充当 Google 的 OAuth 代理：

graph LR
    A[MCP client] <--> B[google-contacts-mcp] <--> C[Google OAuth/API]

1. 服务通过 /.well-known/oauth-authorization-server 将自身公布为 OAuth 授权服务
2. /register 返回 Google OAuth 客户端凭据
3. /authorize 将请求重定向到 Google，并将客户端的回调 URL 编码在 state 中
4. /callback 接收 Google 返回的代码，并转发给客户端的回调地址
5. /token 将令牌请求代理到 Google，并注入客户端凭据
6. /mcp 处理 MCP 请求，使用 bearer token 调用 People API

服务不保存令牌或状态，只负责将 OAuth 请求代理到 Google。

工具

工具	描述
contacts_list	列出联系人，包括姓名、邮箱、电话、组织、生日、事件、URL、地址、昵称、关系、IM 用户名、性别、外部 ID、客户端数据和自定义字段
contacts_search	按姓名、邮箱或电话搜索联系人
directory_search	在组织通讯录中搜索同事
contact_get	获取单个联系人的详细信息
contact_create	创建新联系人
contact_update	更新现有联系人
contact_delete	永久删除联系人
contact_photo_update	设置或替换联系人的照片
contact_photo_delete	移除联系人的照片
contact_groups_list	列出联系人分组（标签）
contact_group_get	获取联系人分组及其成员
contact_group_create	创建新的联系人分组
contact_group_update	重命名联系人分组
contact_group_delete	永久删除联系人分组
contact_group_members_modify	在联系人分组中添加或移除联系人

参与贡献

欢迎在 GitHub 上提交拉取请求！开始贡献的步骤如下：

1. 安装 Git 和 Node.js
2. 克隆仓库
3. 使用 npm install 安装依赖
4. 运行 npm run test 执行测试
5. 使用 npm run build 构建

发布

版本遵循语义化版本规范。

发布步骤：

1. 使用 npm version <major | minor | patch> 更新版本号
2. 运行 git push --follow-tags 推送并附带标签
3. 等待 GitHub Actions 发布到 NPM 注册表。