星战科技xingzhan.cloud
返回市场
谷歌联系人服务器

谷歌联系人服务器

作者：RayanZaki15 星标更新：2025-10-22
安装使用来源：spider==github.com

项目介绍

MseeP.ai 安全评估徽章

📇 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

🚀 初始授权（推荐）

为了获得初始授权流程中的GOOGLE_REFRESH_TOKEN，建议直接在终端中运行mcp-google-contacts命令（而不是在任何可能会隐藏交互式浏览器提示的MCP客户端中）。

示例：

mcp-google-contacts

按照终端和浏览器中的说明完成认证。一旦显示了GOOGLE_REFRESH_TOKEN，您可以将其设置为环境变量以供非交互式使用。

🛠️ 使用方法

🏃‍♂️ 基本启动

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

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

⚙️ 命令行参数

参数描述默认值
--transport使用的传输协议（stdio或http）stdio
--hostHTTP传输的主机localhost
--portHTTP传输的端口8000
--client-idGoogle OAuth客户端ID（覆盖环境变量）-
--client-secretGoogle OAuth客户端密钥（覆盖环境变量）-
--refresh-tokenGoogle OAuth刷新令牌（覆盖环境变量）-
--credentials-fileGoogle 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")
# 或
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/c11111111111111111", 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的配额限制
  • 📝 日志：检查控制台输出中的错误消息和调试信息

👥 贡献

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

📄 许可

本项目根据MIT许可发布 - 详情见LICENSE文件。