📇 MCP Google Contacts Server

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

✨ 功能

• 列出和搜索 Google Contacts
• 创建、更新和删除联系人
• 搜索 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: 您帐户的有效刷新令牌

🛠️ 用法

🏃‍♂️ 基本启动

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 客户端（如 Anthropic 的 Claude 与 Cline）一起使用，请将其添加到您的 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("john.doe@example.com")
# or
get_contact("people/c12345678901234567")

➕ create_contact

在您的 Google Contacts 中创建一个新联系人。

参数：

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

示例：

create_contact(given_name="Jane", family_name="Smith", email="jane.smith@example.com", phone="+1-555-123-4567")

✏️ update_contact

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

参数：

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

示例：

update_contact(resource_name="people/c12345678901234567", email="new.email@example.com")

🗑️ 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 配额限制
• 📝 日志：检查控制台输出中的错误消息和调试信息

👥 贡献

欢迎贡献！ 请随时提交拉取请求。

📄 许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参见 LICENSE 文件。