📇 MCP Google Contacts Server

📇 MCP Google Contacts 服务

一个机器对话协议（MCP）服务，提供 Google Contacts 功能，让 AI 助手能够管理联系人、搜索组织目录，并与 Google Workspace 交互。Gemini AI 在 Gemini CLI 中对其原始版本进行了大量更新。

✨ 功能

• 列出和搜索 Google Contacts
• 创建、更新和删除联系人
• 搜索 Google Workspace 目录
• 查看“其他联系人”（你与其有过互动但尚未添加的人）
• 访问组织中的 Google Workspace 用户

🚀 安装

📋 前提条件

• Python 3.12 或更高版本
• 可访问联系人信息的 Google 账号
• 已启用 People API 的 Google Cloud 项目
• 用于访问 Google API 的 OAuth 2.0 凭据

📦 从源代码安装

要将 mcp-google-contacts-server 安装为 Python 软件包：

1. 克隆仓库：

   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
   cd mcp-google-contacts-server
   

2. 重命名源代码目录： 软件包要求源代码位于名为 mcp_google_contacts_server 的目录中。

   mv src mcp_google_contacts_server
   

3. 安装软件包： 这将安装软件包及其依赖项，并使 mcp-google-contacts 命令可在 PATH 中使用。

   pip install .
   

   注意：如果安装后遇到导入错误，请确保源文件（main.py、tools.py、google_contacts_service.py、formatters.py、config.py）中的相对导入已更新为绝对导入（例如，from mcp_google_contacts_server.module_name import ...）。pip install . 通常会自动处理此问题，但如果软件包结构特殊，有时需要手动调整。

🔑 身份验证设置

该服务需要 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：你账号的有效刷新令牌

注意：如果现有 Google OAuth 客户端 ID 和客户端密钥环境变量的名称不同（例如，GOOGLE_OAUTH_CLIENT_ID），你可以在 .env 文件中为其设置别名（例如，GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID），以确保服务能够正确读取。 例如，在命令行中运行 mcp-google-contacts 之前，使用 export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET：

env | grep GOOGLE
export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET
env | grep GOOGLE
mcp-google-contacts

{authentication evocation should happen here)

🚀 初始授权（推荐）

要获取 GOOGLE_REFRESH_TOKEN 并完成初始授权流程，建议直接在终端中运行 mcp-google-contacts 命令（不要通过可能会隐藏交互式浏览器提示的 MCP 客户端运行）。

示例：

mcp-google-contacts

按照终端和浏览器中的说明完成身份验证。显示 GOOGLE_REFRESH_TOKEN 后，你可以将其设置为环境变量，以便非交互式使用。

🛠️ 使用方法

🏃‍♂️ 基本启动

python src/main.py
# or
uv run src/main.py

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

⚙️ 命令行参数

参数	描述	默认值
--transport	要使用的传输协议（stdio 或 http）	stdio
--host	HTTP 传输的主机	localhost
--port	HTTP 传输的端口	8000
--client-id	Google OAuth 客户端 ID（覆盖环境变量）	-
--client-secret	Google OAuth 客户端密钥（覆盖环境变量）	-
--refresh-token	Google OAuth 刷新令牌（覆盖环境变量）	-
--credentials-file	Google OAuth credentials.json 文件的路径	-

📝 示例

使用 HTTP 传输启动：

python src/main.py --transport http --port 8080

使用指定的凭据文件：

python src/main.py --credentials-file /path/to/your/credentials.json

直接提供凭据：

python src/main.py --client-id YOUR_CLIENT_ID --client-secret YOUR CLIENT_SECRET --refresh-token YOUR_REFRESH_TOKEN

🔌 与 MCP 客户端集成

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

{
  "mcpServers": {
    "google-contacts-server": {
      "command": "uv",
      "args": [
         "--directory",
         "/path/to/mcp-google-contacts-server",
         "run",
        "main.py"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

🧰 可用工具

此 MCP 服务提供以下工具：

工具	描述
list_contacts	列出所有联系人，或按姓名筛选
get_contact	按资源名称或电子邮件地址获取联系人
create_contact	创建新联系人
update_contact	更新现有联系人
delete_contact	按资源名称删除联系人
search_contacts	按姓名、电子邮件或电话号码搜索联系人
list_workspace_users	列出组织目录中的 Google Workspace 用户
search_directory	搜索 Google Workspace 目录中的人员
get_other_contacts	获取“其他联系人”部分中的联系人

🔍 工具详细说明

📋 list_contacts

列出所有 Google 联系人，或按姓名筛选。

参数：

• name_filter（可选）：用于按姓名筛选联系人的字符串
• max_results（可选）：要返回的联系人数量上限（默认值：100）

示例：

list_contacts(name_filter="John", max_results=10)

👤 get_contact

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

参数：

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

示例：

get_contact("[email protected]")
# or
get_contact("people/c12345678901234567")

➕ create_contact

在 Google Contacts 中创建新联系人。

参数：

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

示例：

create_contact(given_name="Jane", family_name="Smith", email="[email protected]", phone="+1-555-123-4567")

✏️ update_contact

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

参数：

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

示例：

update_contact(resource_name="people/c12345678901234567", email="[email protected]")

🗑️ delete_contact

从 Google Contacts 中删除联系人。

参数：

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

示例：

delete_contact(resource_name="people/c12345678901234567")

🔍 search_contacts

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

参数：

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

示例：

search_contacts(query="john", max_results=5)

🏢 list_workspace_users

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

参数：

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

示例：

list_workspace_users(query="engineering", max_results=25)

🔭 search_directory

在组织的 Google Workspace 目录中执行定向搜索。

参数：

• query：用于查找特定目录成员的搜索词
• max_results（可选）：要返回的结果数量上限（默认值：20）

示例：

search_directory(query="product manager", max_results=10)

👥 get_other_contacts

从“其他联系人”部分检索联系人——这些是你曾互动过但尚未添加到联系人的对象。

参数：

• max_results（可选）：要返回的结果数量上限（默认值：50）

示例：

get_other_contacts(max_results=30)

🔒 权限

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

❓ 故障排除

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

👥 贡献

欢迎贡献！请随时提交 Pull Request。

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。