关键词

Google通讯录AI助手集成无服务器OAuth认证实时数据访问

项目简介

Google通讯录MCP服务器是一个生产级的无服务器应用，专为集成AI助手（如Claude）而设计。它遵循Model Context Protocol (MCP)，允许AI助手通过安全的、按用户OAuth认证的方式访问和管理用户的Google通讯录数据。所有通讯录数据都是实时从Google获取，不进行服务器端存储，最大限度地确保用户隐私和数据安全。

主要功能点

  • 安全认证: 支持OAuth 2.1，每个用户通过自己的Google账户进行认证，确保数据访问权限精确到个人。
  • 无数据存储: 服务器不存储任何通讯录数据，仅存储加密的OAuth令牌，所有通讯录信息实时从Google People API获取，最大限度保护用户隐私。
  • 无服务器架构: 基于AWS Lambda构建，利用AWS API Gateway、DynamoDB等服务实现自动扩缩容，按需付费，无需管理底层基础设施。
  • AI助手集成: 可与Claude Web和Claude Desktop等AI助手无缝集成，提供统一的上下文服务访问接口。
  • 工具集: 提供以下工具，供AI助手调用以执行特定操作：
    • 'list_contacts'：列出认证用户的所有通讯录联系人，支持分页和排序。
    • 'get_contact'：根据联系人ID（resourceName）获取特定联系人的详细信息。
    • 'search_contacts'：在所有通讯录字段中搜索联系人，如姓名、电话、邮件等。
    • 'search_directory'：搜索Google Workspace目录联系人（此功能仅适用于Google Workspace账户）。

安装步骤

  1. 前提条件:

    • 安装Node.js (推荐版本 >= 18.0.0)。
    • 配置好AWS CLI，并确保您的AWS账户有足够的权限部署Lambda、API Gateway和DynamoDB等资源。
    • 在Google Cloud项目中启用了People API。
    • 安装AWS CDK：'npm install -g aws-cdk'。

  2. 项目克隆与依赖安装:

    git clone https://github.com/OffleashXYZ/google-contacts-mcp-server.git
cd google-contacts-mcp-server
npm install

  3. Google OAuth配置:

    • 前往Google Cloud Console。
    • 确保已启用People API。
    • 创建OAuth 2.0凭据，选择“Web 应用程序”类型。
    • 记下您获得的'client_id'和'client_secret'。
    • 暂时跳过重定向URI的添加，您将在部署后获得准确的重定向URI。

  4. 部署到AWS: 在项目根目录下运行以下命令来构建和部署服务器到您的AWS账户：

    # 构建TypeScript代码
npm run build

# 构建Lambda部署包
npm run build:lambda

# 使用CDK部署AWS资源
npm run cdk:deploy

    部署完成后，您将在终端看到CDK输出，其中包含MCP服务器的API Endpoint、Google OAuth回调URL等重要信息。

  5. 配置OAuth凭据: 部署后，您需要将Google OAuth的'client_id'和'client_secret'配置到AWS Systems Manager Parameter Store中。请将 'YOUR_CLIENT_ID' 和 'YOUR_CLIENT_SECRET' 替换为实际值，并将 'YOUR_AWS_REGION' 替换为您的AWS部署区域：

    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 YOUR_AWS_REGION

    重要: 复制CDK输出中的'GoogleCallbackUrl' (例如：'https://abc123.execute-api.us-west-2.amazonaws.com/google/callback')。 返回Google Cloud Console -> APIs & Services -> 凭据，编辑您的OAuth 2.0客户端ID，将这个'GoogleCallbackUrl'添加到“Authorized redirect URIs”中。

服务器配置 (针对MCP客户端)

此MCP服务器是基于HTTP协议部署的远程服务。因此，MCP客户端（如Claude）无需配置本地启动命令和参数。客户端只需配置一个MCP服务器的URL，通过该URL与远程服务器建立连接。这个URL在您完成AWS部署后，会从CDK输出中获得。

  • 对于Claude Web:

    1. 访问Claude.ai -> Settings -> Integrations。
    2. 点击“Add server”。
    3. 在提供的输入框中，输入您的MCP服务器URL。该URL的格式通常为 'https://[您的API_ENDPOINT]/mcp'（API_ENDPOINT可在CDK输出中找到）。
    4. 点击“Connect”，然后按照提示使用您的Google账户进行认证。

  • 对于Claude Desktop: 如果您使用Claude Desktop，您需要编辑其配置文件 'claude_desktop_config.json'。在该文件中，找到或添加 'mcpServers' 部分，并配置一个名为 'google-contacts' 的服务器。其中，'url' 参数的值就是您部署后获得的MCP服务器URL。

    {
  "mcpServers": {
    "google-contacts": {
      "url": "https://your-api-id.execute-api.region.amazonaws.com/mcp" 
    }
  }
}
    • '"google-contacts"': 这是您为该服务器定义的名称，AI助手会用它来识别此MCP服务。
    • '"url"': 这是MCP服务器的访问地址，AI助手将通过这个URL与服务器通信。请务必将示例中的 'https://your-api-id.execute-api.region.amazonaws.com/mcp' 替换为您实际部署的MCP服务器URL。

    重启Claude Desktop后，首次使用该服务器时将提示进行Google认证。

基本使用方法

一旦MCP服务器与AI助手（如Claude）连接并认证成功，AI助手即可通过调用服务器提供的工具来访问和操作您的Google通讯录。例如，您可以直接向AI助手提问：

  • “我的通讯录里有多少联系人？”（AI助手将可能调用 'list_contacts' 工具）
  • “帮我查找名叫‘张三’的联系人信息。”（AI助手将可能调用 'search_contacts' 工具）
  • “获取我老板的电话号码。”（AI助手将根据您的提问，智能地选择并执行 'search_contacts' 或 'get_contact' 工具来获取所需信息。） AI助手会根据您的指令，自动选择并执行相应的工具来获取信息，并通过AI为您呈现结果。

信息

分类

AI与计算

访问项目