Google Contacts MCP Server

Google 联系人 MCP 服务器

基于AWS Lambda的无服务器MCP服务器，用于Google联系人，支持按用户OAuth认证

由……开发 无牵引绳（训练/活动）

概述

一个可投入生产的模型上下文协议（MCP）服务器，使像Claude这样的AI助手能够通过安全的无服务器架构访问Google联系人。每位员工使用自己的Google帐户进行身份验证，联系人数据实时传输，无需存储。

主要特点

• 每个用户的OAuth 2.1认证 - 每位员工使用自己的Google联系人
• 零接触数据存储 - 仅存储OAuth令牌，联系人实时获取
• 无服务器 AWS Lambda - 自动扩展，按使用量付费，无需基础设施管理
• 隐私优先的DynamoDB - 仅存储具有自动过期时间（TTL）的令牌
• 与Claude网页版和桌面版兼容 - 单个URL适用于两种访问方式
• 只读访问 - 用途 contacts.readonly 仅限范围

建筑

Employee → Claude (Web/Desktop) → API Gateway → Lambda → Google Contacts API
                                       ↓
                                   DynamoDB
                                (OAuth tokens only)

组件

• AWS Lambda - 使用Streamable HTTP传输协议托管Express.js MCP服务器
• API网关HTTP API - 曝光 /mcp 带有CORS和OAuth 2.1端点的终端点
• DynamoDB 表：

- sessions - 存储OAuth令牌并设置TTL（不存储联系数据！） - oauth-clients - 动态客户端注册（DCR） - auth-codes - 临时授权码（有效期10分钟）

• AWS Systems Manager 参数存储 - 存储Google OAuth客户端凭据
• AWS CDK（Amazon Web Services Cloud Development Kit，亚马逊网络服务云开发工具包） - 以代码形式管理的基础设施进行部署

快速入门

先决条件

• Node.js 版本 >= 18.0.0
• 已配置CLI的AWS账户
• 已启用People API的Google Cloud项目
• 已安装 AWS CDK： npm install -g aws-cdk

1. 安装依赖项

npm install

2. 配置Google OAuth

1. 首选 Google 云控制台
2. 启用 人员API
3. 创建OAuth 2.0凭据（Web应用程序类型）
4. 记下你的 client_id 并且 client_secret
5. 添加重定向URI（部署后会获得此信息）： https://your-api-id.execute-api.region.amazonaws.com/google/callback

3. 部署到AWS

# Build TypeScript
npm run build

# Build Lambda package
npm run build:lambda

# Deploy with CDK
npm run cdk:deploy

4. 配置OAuth凭据

部署后，请在AWS Systems Manager参数存储中更新Google OAuth凭据：

aws ssm put-parameter \
  --name "/google-contacts-mcp/oauth-credentials" \
  --value '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}' \
  --type String \
  --overwrite \
  --region us-west-2

注： 重定向URI是动态构建的，如下所示： ${API_ENDPOINT}/google/callback - 你无需将其包含在参数中。

5. 在Google中添加重定向URI

复制 GoogleCallbackUrl 从CDK输出中获取并将其添加到您的Google OAuth凭据中：

• 前往 Google Cloud Console → API 与服务 → 凭据
• 编辑您的OAuth 2.0客户端ID
• 将回调URL添加到“授权重定向URI”中（例如。， https://abc123.execute-api.us-west-2.amazonaws.com/google/callback)

使用

克劳德·韦布

1. 访问 Claude.ai → 设置 → 集成
2. 点击“添加服务器”
3. 请输入您的MCP服务器URL： https://your-api-id.execute-api.region.amazonaws.com/mcp
4. 点击“连接”
5. 当系统提示时，请使用您的谷歌账户进行身份验证

就是这样！Claude 将自动处理 OAuth 2.1 的流程。

克劳德桌面版

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "google-contacts": {
      "url": "https://your-api-id.execute-api.region.amazonaws.com/mcp"
    }
  }
}

重启Claude桌面版。首次使用服务器时，您将被重定向到Google进行身份验证。

可用工具

1. list_contacts

列出联系人，并分页显示。

参数：

• pageSize （可选）：联系人数量（1-1000，默认：100）
• pageToken （可选）：分页令牌
• sortOrder （可选）：排序顺序（按姓氏升序等）

2. get_contact

获取特定联系人的详细信息。

参数：

• resourceName （必填）：联系人ID（例如。， people/c1234567890）

3. search_contacts

在所有联系人字段中搜索。

参数：

• query （必填）：搜索词
• pageSize （可选）：结果数量（默认：100）
• readMask （可选）：要返回的特定字段

4. search_directory

搜索Google Workspace目录（仅限Workspace账户）。

参数：

• query （必填）：搜索词
• pageSize （可选）：结果数量（默认：100）
• pageToken （可选）：分页令牌

隐私与安全

我们存储的内容

✅ OAuth访问令牌（加密，自动过期） ✅ OAuth刷新令牌（加密，自动过期） ✅ 用户电子邮件（用于会话管理） ✅ 令牌过期时间戳

我们不存储的内容

❌ 联系人姓名、电子邮件、电话号码 ❌ 搜索查询 ❌ 任何联系数据

所有联系数据实时通过服务器传输，且从不持久存储。

发展

# Install dependencies
npm install

# Build TypeScript
npm run build

# Build Lambda package
npm run build:lambda

# Type checking
npm run typecheck

# Deploy to AWS
npm run cdk:deploy

# Destroy AWS resources
npm run cdk:destroy

项目结构

google-contacts-mcp/
├── bin/
│   └── app.ts                    # CDK app entry point
├── lib/
│   └── google-contacts-mcp-stack.ts  # CDK infrastructure definition
├── src/
│   ├── lambda.ts                 # Lambda handler entry point
│   ├── app.ts                    # Express application setup
│   ├── mcp-service.ts            # MCP protocol implementation
│   ├── oauth-provider.ts         # OAuth 2.1 provider implementation
│   ├── oauth-client-store.ts     # DynamoDB OAuth client registry
│   ├── auth-code-store.ts        # DynamoDB authorization code storage
│   ├── session-manager.ts        # DynamoDB session/token storage
│   ├── contacts.ts               # Google Contacts API calls
│   └── types.ts                  # TypeScript type definitions
├── public/
│   └── logo.png                  # Server icon
├── package.json
├── tsconfig.json
├── cdk.json                      # CDK configuration
└── README.md

成本

采用AWS Lambda的按使用量付费模式：

• Lambda每100万次请求约0.20美元
• API网关每100万次请求约1.00美元
• DynamoDB（注：DynamoDB是亚马逊提供的一种完全托管的NoSQL数据库服务，这里直接保留原英文名称，因为它是专有名词）每100万次读/写请求约0.25美元
• 参数存储（标准字符串参数）免费（标准吞吐量）

一个50人团队的典型月度成本：约3-8美元/月

故障排除

“需要身份验证”

在Claude中点击“连接”按钮，并使用您的Google账户进行身份验证。

“无效或过期的访问令牌”

您的会话已过期。请点击“连接”以重新进行身份验证。

“未能加载OAuth凭据”

在 AWS Systems Manager 参数存储中更新参数，使用您的正确 Google OAuth 客户端 ID 和密钥。

“请求缺少必需的身份验证凭据”（谷歌错误）

检查您的 Google Cloud Console OAuth 同意屏幕是否包含正确的范围：

• https://www.googleapis.com/auth/contacts.readonly
• https://www.googleapis.com/auth/userinfo.email

“目录搜索仅适用于 Google Workspace”

search_directory 需要一个Workspace帐户。请使用 search_contacts 相反。

支持

• 文档见 QUICKSTART.md 翻译为中文是：“快速入门指南.md”
• 问题:
• 商业支持联系 无牵引绳（或“自由奔跑”）

许可证

这个项目采用以下许可协议 知识共享署名-非商业性使用-相同方式共享 4.0 国际许可协议（CC BY-NC-SA 4.0）.

这意味着：

• ✅ 可免费用于个人及公司内部用途
• ✅ 必须感谢Offleash
• ❌ 不得用于商业销售或使用
• ❌ 修改必须使用相同的许可证

见 许可证 请查阅完整条款或访问 https://creativecommons.org/licenses/by-nc-sa/4.0/

关于Offleash

由……建造/建立 无牵引绳（或：脱绳） - 为团队提供AI驱动的工具，增强其能力。

______________________________________________________________________

版本1.0.0 最后更新时间2025年10月