MCP Google Contacts Server

📇 MCP Google 通讯录服务器

提供 Google 通讯录功能的机器对话协议 (MCP) 服务器，允许 AI 助手管理联系人、搜索您组织的目录以及与 Google Workspace 交互。

✨ 特点

• 列出并搜索 Google 通讯录
• 创建、更新和删除联系人
• 搜索 Google Workspace 目录
• 查看“其他联系人”（与您互动过但尚未添加的人）
• 访问您单位中的 Google Workspace 用户

🚀 安装

📋 先决条件

• Python 3.12 或更高版本
• 具有联系人访问权限的 Google 帐户
• 启用 People API 的 Google Cloud 项目
• 用于访问 Google API 的 OAuth 2.0 凭据

🧪 使用 uv（推荐）

1. 如果尚未安装 uv，请安装它：
   pip install uv
2. 克隆存储库：
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
3. 创建虚拟环境并安装依赖项：
   uv venv source .venv/bin/activate uv pip install -r requirements.txt

📦使用 pip

1. 克隆存储库：
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server
2. 安装依赖项：
   pip install -r requirements.txt

🔑 身份验证设置

服务器需要 Google API 凭据才能访问您的联系人。您有以下几种选择：

🔐 选项 1：使用 credentials.json 文件

1. 创建 Google Cloud 项目并启用 People API
2. 创建 OAuth 2.0 凭据（桌面应用程序类型）
3. 下载 credentials.json 文件
4. 将其放置在以下位置之一：
   • 本项目的根目录
   • 您的主目录（~/google-contacts-credentials.json）
   • 使用--credentials-file参数指定其位置

🔐 选项 2：使用环境变量

设置以下环境变量：

• GOOGLE_CLIENT_ID ：您的 Google OAuth 客户端 ID
• GOOGLE_CLIENT_SECRET ：您的 Google OAuth 客户端密钥
• GOOGLE_REFRESH_TOKEN ：您帐户的有效刷新令牌

🛠️ 使用方法

🏃‍♂️ 基本启动

这将使用默认的 stdio 传输启动服务器。

⚙️ 命令行参数

📝 示例

从 HTTP 传输开始：

使用特定的凭证文件：

直接提供凭证：

🔌 与 MCP 客户端集成

要将此服务器与 MCP 客户端（如 Anthropic 的 Claude 和 Cline）一起使用，请将其添加到您的 MCP 配置中：

🧰 可用工具

该 MCP 服务器提供以下工具：

🔍 详细工具描述

📋 list_contacts

列出您的所有 Google 联系人或按姓名过滤。

参数：

• name_filter （可选）：按名称过滤联系人的字符串
• max_results （可选）：返回的最大联系人数量（默认值：100）

例子：

👤 get_contact

检索有关特定联系人的详细信息。

参数：

• identifier ：资源名称（people/*）或联系人的电子邮件地址

例子：

➕ create_contact

在您的 Google 通讯录中创建新联系人。

参数：

• given_name ：联系人的名字
• family_name （可选）：联系人的姓氏
• email （可选）：联系人的电子邮件地址
• phone （可选）：联系人的电话号码

例子：

✏️ update_contact

使用新信息更新现有联系人。

参数：

• resource_name ：联系资源名称（people/*）
• given_name （可选）：更新后的名字
• family_name （可选）：更新后的姓氏
• email （可选）：更新后的电子邮件地址
• phone （可选）：更新后的电话号码

例子：

🗑️ delete_contact

从您的 Google 通讯录中删除联系人。

参数：

• resource_name ：要删除的联系人资源名称 (people/*)

例子：

🔍 search_contacts

按姓名、电子邮件或电话号码搜索您的联系人。

参数：

• query ：在联系人中查找的搜索词
• max_results （可选）：返回的最大结果数（默认值：10）

例子：

🏢 list_workspace_users

列出您组织目录中的 Google Workspace 用户。

参数：

• query （可选）：用于查找特定用户的搜索词
• max_results （可选）：返回的最大结果数（默认值：50）

例子：

🔭 search_directory

对您组织的 Google Workspace 目录执行有针对性的搜索。

参数：

• query ：搜索词以查找特定目录成员
• max_results （可选）：返回的最大结果数（默认值：20）

例子：

👥 get_other_contacts

从“其他联系人”部分检索联系人 - 与您互动但尚未添加到联系人中的人。

参数：

• max_results （可选）：返回的最大结果数（默认值：50）

例子：

🔒 权限

首次运行服务器时，您需要通过 Google 进行身份验证并授予访问联系人所需的权限。身份验证流程将引导您完成此过程。

❓ 故障排除

• 🔐 身份验证问题：确保您的凭据有效并具有必要的范围
• ⚠️ API 限制：请注意 Google People API 配额限制
• 📝 日志：检查控制台输出中的错误消息和调试信息

👥 贡献

欢迎贡献代码！欢迎提交 Pull 请求。

📄 许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。