📇 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，请先安装：
   bash
   pip install uv

2. 克隆仓库：
   bash
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
   cd mcp-google-contacts-server

3. 创建虚拟环境并安装依赖项：
   bash
   uv venv
   source .venv/bin/activate
   uv pip install -r requirements.txt

📦 使用 pip

1. 克隆仓库：
   bash
   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
   cd mcp-google-contacts-server

2. 安装依赖项：
   bash
   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：您的账户的有效刷新令牌

🛠️ 使用方法

🏃‍♂️ 基本启动

bash
python src/main.py

或者

uv run src/main.py

这将以默认的 stdio 传输方式启动服务器。

⚙️ 命令行参数

📝 示例

使用 HTTP 传输启动：
bash
python src/main.py --transport http --port 8080

使用特定的凭证文件：
bash
python src/main.py --credentials-file /path/to/your/credentials.json

直接提供凭证：
bash
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 配置中：

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

🧰 可用工具

此 MCP 服务器提供了以下工具：

🔍 工具详细说明

📋 list_contacts

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

参数：

• name_filter (可选)：用于按姓名过滤联系人的字符串
• max_results (可选)：要返回的最大联系人数（默认值：100）

示例：
python
list_contacts(name_filter="John", max_results=10)

👤 get_contact

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

参数：

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

示例：
python
get_contact("john.doe@example.com")

或

get_contact("people/c12345678901234567")

➕ create_contact

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

参数：

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

示例：
python
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 (可选)：更新后的电话号码

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

🗑️ delete_contact

从您的 Google 联系人中删除一个联系人。

参数：

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

示例：
python
delete_contact(resource_name="people/c12345678901234567")

🔍 search_contacts

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

参数：

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

示例：
python
search_contacts(query="john", max_results=5)

🏢 list_workspace_users

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

参数：

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

示例：
python
list_workspace_users(query="engineering", max_results=25)

🔭 search_directory

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

参数：

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

示例：
python
search_directory(query="product manager", max_results=10)

👥 get_other_contacts

从“其他联系人”部分检索联系人——这些是您曾与之互动但尚未添加到您的联系人列表中的人。

参数：

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

示例：
python
get_other_contacts(max_results=30)

🔒 权限

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

❓ 故障排除

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

👥 贡献

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

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。