AI导哈

Google Contacts MCP服务器

一个为Google Contacts API实现的模型上下文协议(MCP)服务器，通过OAuth 2.0认证使AI助手能够与Google Contacts交互。

  • by EmilyThaHuman
  • 本地部署
  • 更新于
在 GitHub 查看 EmilyThaHuman/google-contacts-mcp-server

使用说明

谷歌联系人MCP服务器

用于Google联系人API的模型上下文协议（MCP）服务器实现，使人工智能助手能够通过OAuth 2.0身份验证与Google联系人进行交互。

特性

  • 完成Google联系人API集成

    • 通过搜索和筛选列出联系人
    • 获取个人联系方式
    • 创建新联系人
    • 更新现有联系人
    • 删除联系人
    • 列出联系人组

  • OAuth 2.0身份验证

    • 安全的Google OAuth流
    • 自动令牌刷新
    • 会话管理

  • MCP协议支持

    • 流式HTTP服务器传输
    • 多个并发会话
    • 基于工具的操作

  • 生产就绪

    • TypeScript实现
    • 全面的错误处理
    • 请求日志记录
    • CORS支持
    • 健康监测

先决条件

  • Node.js 18+或兼容的运行时环境
  • 启用人员API的谷歌云项目
  • Google OAuth 2.0凭据（客户端ID和密码）

安装

  1. 克隆存储库：
git clone <repository-url>
cd google-contacts-mcp-server
  1. 安装依赖项：
npm install
  1. 配置环境变量：
cp env.example .env

编辑 .env 并添加您的Google OAuth凭据：

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:3003/oauth/callback
FRONTEND_URL=http://localhost:5173

谷歌云设置

  1. 首选 谷歌云控制台
  2. 创建新项目或选择现有项目
  3. 启用 人民API
  4. 转到“凭据”→ “创建凭据”→ “OAuth 2.0客户端ID”
  5. 配置OAuth同意屏幕
  6. 添加授权重定向URI：
    • http://localhost:3003/oauth/callback （发展）
    • 您的生产回调URL
  7. 将客户端ID和客户端密码复制到 .env

发展

使用热重载启动开发服务器：

npm run dev

服务器将于启动 http://localhost:3003 （可通过以下方式配置 PORT 有人）。

建筑

将TypeScript构建为JavaScript：

npm run build

运行构建版本：

npm start

API终点

健康检查

GET /health

返回服务器状态和版本。

OAuth流

1.获取授权URL

GET /oauth/authorize?userId=<user_id>&state=<state>

2.OAuth回调 （自动）

GET /oauth/callback?code=<code>&state=<state>

3.刷新令牌

POST /oauth/refresh
Body: { userId: string, refreshToken: string }

4.断开连接

POST /oauth/disconnect
Body: { userId: string }

MCP协议

初始化会话

POST /mcp
Content-Type: application/json
Body: MCP initialize request

工具执行

POST /mcp
Mcp-Session-Id: <session_id>
Body: MCP tool call request

会话通知（SSE）

GET /mcp
Mcp-Session-Id: <session_id>

MCP工具

1.google_contacts_list

列出并搜索联系人。

输入：

  • userId （必填）：用于身份验证的用户ID
  • query （可选）：搜索查询
  • maxResults （可选）：最大结果（默认值：100，最大值：1000）
  • sortOrder （可选）：排序顺序（默认：LAST_MODIFIED_DESENDING）

输出： 包含详细信息的联系人数组。

2.google_contacts_get

按资源名称获取特定联系人。

输入：

  • userId （必填）：用于身份验证的用户ID
  • resourceName （必填）：联系人资源名称（例如，“people/c123456”）

输出： 联系方式。

3.google_contacts_create

创建新联系人。

输入：

  • userId （必填）：用于身份验证的用户ID
  • givenName （可选）：名字
  • familyName （可选）：姓氏
  • emailAddresses （可选）：电子邮件地址数组
  • phoneNumbers （可选）：电话号码数组
  • organizations （可选）：组织数组

输出： 已创建联系方式。

4.google_contacts_update

更新现有联系人。

输入：

  • userId （必填）：用于身份验证的用户ID
  • resourceName （必填）：联系人资源名称
  • updatePersonFields （必填）：要更新的字段（例如，[“姓名”、“电子邮件地址”]）
  • 其他要更新的字段

输出： 更新了联系方式。

5.谷歌联系人删除

删除联系人。

输入：

  • userId （必填）：用于身份验证的用户ID
  • resourceName （必填）：联系人资源名称

输出： 成功确认。

6.谷歌联络小组

列出联系人组。

输入：

  • userId （必填）：用于身份验证的用户ID

输出： 联系人组数组。

用法示例

JavaScript/TypeScript客户端

import { MCPClient } from '@modelcontextprotocol/sdk/client';

// Initialize MCP client
const client = new MCPClient({
  serverUrl: 'http://localhost:3003/mcp',
  transport: 'streamable-http',
});

// Connect to server
await client.connect();

// List contacts
const result = await client.callTool('google_contacts_list', {
  userId: 'user123',
  query: 'john',
  maxResults: 10,
});

console.log(result.contacts);

使用AI助手

此MCP服务器可以与支持模型上下文协议的AI助手集成：

  1. 使用MCP服务器URL配置AI助手
  2. 通过OAuth流对用户进行身份验证
  3. 人工智能可以使用自然语言与联系人进行交互：
    • “显示我的所有联系人”
    • “通过电子邮件为John Doe创建联系人john@example.com"
    • “将Jane的电话号码更新为555-1234”

部署

Cloudflare员工

部署到Cloudflare Workers进行生产：

# Create KV namespace for sessions
npm run kv:create

# Update wrangler.toml with namespace ID

# Deploy
npm run deploy

传统主机

将构建的服务器部署到任何Node.js托管平台：

  1. 构建： npm run build
  2. 设置环境变量
  3. 开始： npm start

配置

环境变量：

变量 描述 默认值
PORT 服务器端口 3003
NODE_ENV 环境 development
GOOGLE_CLIENT_ID Google OAuth客户端ID （必填）
GOOGLE_CLIENT_SECRET Google OAuth客户端密码 （必填）
GOOGLE_REDIRECT_URI OAuth回调URL http://localhost:3003/oauth/callback
FRONTEND_URL 前端应用程序URL http://localhost:5173

安全

  • OAuth令牌存储在内存中（基于会话）
  • 对于生产，实施持久存储（数据库或KV存储）
  • 所有端点都支持具有可配置源的CORS
  • 过期时自动刷新令牌
  • 使用状态参数保护OAuth 2.0流

错误处理

服务器提供全面的错误消息：

  • 400错误请求：参数无效或缺少必填字段
  • 401未经授权：需要身份验证或令牌已过期
  • 403禁止：权限不足
  • 404未找到：未找到联系人或资源
  • 500内部服务器错误：服务器端错误

日志记录

不同级别的结构化日志记录：

  • debug：请求详细信息（仅用于开发）
  • info：一般业务
  • warn：非关键问题
  • error：堆栈跟踪出现严重错误

贡献

欢迎投稿！拜托：

  1. 分叉存储库
  2. 创建要素分支
  3. 进行更改
  4. 如果适用，添加测试
  5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于问题、疑问或贡献：

  • 在GitHub上打开一个问题
  • 检查现有文档
  • 查看INTEGRATION.md指南

相关项目

由ZeroTwo提供技术支持

此Google Contacts MCP连接器是 ZeroTwo人工智能平台 --一体化的人工智能工作区，让您通过GPT-5、Claude和Gemini搜索、创建和管理您的谷歌联系人。
🌐 ZeroTwo——一个应用程序中的所有AI模型 使用GPT-5、Claude和Gemini管理您的谷歌联系人——所有这些都在一个地方。
✨ 零两个功能 人工智能联系人管理、电子邮件起草、网络搜索和MCP驱动的谷歌工作区工具。
🤖 人工智能模型——GPT-5、克劳德和双子座 使用世界上最好的人工智能来组织联系人、查找人员和起草外联信息。
🔌 ZeroTwo连接器和集成 将Google联系人、Gmail、Google日历等连接到您的AI工作流程。
💰 零二定价 一个替代ChatGPT Plus、Claude Pro和Gemini Advanced的订阅。
📝 ZeroTwo博客 AI CRM提示、联系人管理指南和ZeroTwo产品更新。
🚀 免费试用ZeroTwo 让AI组织你的联系人——今天就免费开始吧。

专为ZeroTwo打造 --使用此Google联系人MCP服务器 ZeroTwo的AI连接器系统 通过自然语言搜索联系人、创建新联系人和管理您的Google People数据。

相关 MCP