# RayanZaki
## 基本信息
- Slug: `rayanzaki-mcp-google-contacts-server`
- Source: modelscope
- Publisher: @RayanZaki/mcp-google-contacts-server
- Categories: communication / customer-data-platforms
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@RayanZaki/mcp-google-contacts-server
## 简介
暂无描述。
## MCP Server 详情

# 📇 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 传输方式启动服务器。

### ⚙️ 命令行参数

| 参数 | 描述 | 默认值 |
|----------|-------------|---------------|
| `--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 传输启动：
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` | 列出所有联系人或按名称过滤 || `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）

**示例：**
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 文件。