📇 MCP Google Contacts Server
2025.03.22
1
Python联系人管理Google Workspace集成交流协作
MCP Google Contacts Server 是一个基于机器对话协议（MCP）的服务，提供Google Contacts功能，允许AI助手管理联系人、搜索组织目录并与Google Workspace交互。
View on GitHub
Overview
📇 产品定位
MCP Google Contacts Server 是一个基于机器对话协议（MCP）的服务，提供Google Contacts功能，允许AI助手管理联系人、搜索组织目录并与Google Workspace交互。
✨ 核心功能
- 列出和搜索Google联系人
- 创建、更新和删除联系人
- 搜索Google Workspace目录
- 查看"其他联系人"（与您互动但未添加的人）
- 访问组织中的Google Workspace用户
🚀 适用场景
- AI助手管理联系人
- 组织目录搜索
- Google Workspace集成
🧰 工具列表
| 工具 | 描述 |
|---|---|
list_contacts |
列出所有联系人或按名称过滤 |
get_contact |
通过资源名称或电子邮件获取联系人 |
create_contact |
创建新联系人 |
update_contact |
更新现有联系人 |
delete_contact |
通过资源名称删除联系人 |
search_contacts |
按名称、电子邮件或电话号码搜索联系人 |
list_workspace_users |
列出组织目录中的Google Workspace用户 |
search_directory |
在Google Workspace目录中搜索人员 |
get_other_contacts |
从"其他联系人"部分检索联系人 |
❓ 常见问题解答
- 🔐 认证问题：确保您的凭据有效并具有必要的范围
- ⚠️ API限制：注意Google People API配额限制
- 📝 日志：检查控制台输出以获取错误消息和调试信息
🚀 使用教程
📋 使用依赖
- Python 3.12或更高版本
- 具有联系人访问权限的Google帐户
- 启用了People API的Google Cloud项目
- 用于Google API访问的OAuth 2.0凭据
🧪 使用uv（推荐）
-
安装uv（如果尚未安装）：
bash pip install uv -
克隆存储库：
bash git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server -
创建虚拟环境并安装依赖项：
bash uv venv source .venv/bin/activate uv pip install -r requirements.txt
📦 使用pip
-
克隆存储库：
bash git clone https://github.com/rayanzaki/mcp-google-contacts-server.git cd mcp-google-contacts-server -
安装依赖项：
bash pip install -r requirements.txt
🔑 认证设置
🔐 选项1：使用credentials.json文件
- 创建Google Cloud项目并启用People API
- 创建OAuth 2.0凭据（桌面应用程序类型）
- 下载credentials.json文件
- 将其放在以下位置之一：
- 项目的根目录
- 您的主目录（~/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
# 或
uv run src/main.py
⚙️ 命令行参数
| 参数 | 描述 | 默认值 |
|---|---|---|
--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