Google联系人管理服务器

📇 MCP Google 联系人服务器

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

✨ 特点

• 列出并搜索Google联系人
• 创建、更新和删除联系人
• 搜索 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) 以确保服务器能正确接收它们。 例如使用。 export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET 在命令行之前： mcp-google-contacts :

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

（认证调用应在此处发生）

🚀 初始授权（推荐）

为了获取您的初始授权流程 GOOGLE_REFRESH_TOKEN建议运行 mcp-google-contacts 在你的终端中直接输入命令（无需使用任何可能遮蔽交互式浏览器提示的MCP客户端）。

示例：

mcp-google-contacts

按照终端和浏览器中的指示完成身份验证。一旦 GOOGLE_REFRESH_TOKEN 当显示时，您可以将其设置为非交互式使用的环境变量。

🛠️ 使用方法

🏃‍♂️ 初级创业

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

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

⚙️ 命令行参数

📝 示例

从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

列出您所有的谷歌联系人或按姓名进行筛选。

参数：

• 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联系人中创建一个新的联系人。

参数：

• 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联系人中删除一个联系人。

参数：

• 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文件。