](https://mseep.ai/app/rayanzaki-mcp-google-contacts-server)
📇 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包：
- 克隆仓库：
git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
cd mcp-google-contacts-server- 重命名源目录：
该软件包期望源代码位于一个名为（指定名称）的目录中 mcp_google_contacts_server.
mv src mcp_google_contacts_server- 安装该软件包：
这将安装该软件包及其依赖项，从而使 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文件
- 创建一个Google Cloud项目并启用People API
- 创建OAuth 2.0凭据（桌面应用程序类型）
- 下载 credentials.json 文件
- 将其放置在以下位置之一：
- 这个项目的根目录 - 您的主目录（~/google-contacts-credentials.json） - 用……指定其位置 --credentials-file 论点；争论；论据
🔐 选项2：使用环境变量
设置以下环境变量：
GOOGLE_CLIENT_ID您的Google OAuth客户端IDGOOGLE_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传输方式启动服务器。
⚙️ 命令行参数
| 参数 | 描述 | 默认值 |
|---|---|---|
--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
列出您所有的谷歌联系人或按姓名进行筛选。
参数：
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文件。
