MCP Google Contacts Server

🚀 MCP Google Contacts Server

MCP Google Contacts Server 是一个基于 Google People API 构建的联系人管理工具，它能帮助用户高效管理和操作 Google 账户中的联系人数据，支持创建、更新、删除和搜索等操作。

🚀 快速开始

MCP Google Contacts Server 是一个基于 Google People API 构建的联系人管理工具，可帮助用户高效管理和操作 Google 账户中的联系人数据。

✨ 主要特性

• 联系人管理：支持添加、编辑和删除联系人
• 搜索功能：提供多种搜索方式，包括按姓名、邮箱和电话号搜索
• 目录查询：允许搜索组织的 Google Workspace 目录中的用户
• 其他联系人：可查看与你互动过但未添加到联系人列表的人
• 批量操作：支持一次操作多个联系人
• 高扩展性：便于集成到各种应用程序和系统中

📦 安装指南

安装依赖

在运行此工具之前，需确保安装了以下库：

pip install google-auth google-auth-oauthlib googleapis-common-protos google-resourceliker python-dotenv

创建配置文件

创建一个名为 .env 的文件，并添加你的 Google API 密钥：

GOOGLE_API_KEY=your_api_key_here

启动服务

运行以下命令启动 MCP Google Contacts Server：

python main.py

💻 使用示例

基础用法

以下是工具提供的主要功能及其使用方法：

1. 列出联系人 (list_contacts)

# 显示所有Google Contacts或根据名称过滤。
list_contacts(name_filter="张三", max_results=50)

功能：显示所有 Google Contacts 或根据名称过滤。 参数：

• name_filter（可选）：按姓名筛选联系人
• max_results（可选）：设置返回的最大结果数，默认为 100

2. 获取联系人信息 (get_contact)

# 获取指定联系人的详细信息。
get_contact("zhangsan@example.com")
# 或
get_contact("people/12345678901234567")

功能：获取指定联系人的详细信息。 参数：

• identifier：联系人资源 ID（people/*）或邮箱地址

3. 创建新联系人 (create_contact)

# 添加新的联系人到Google Contacts。
create_contact(given_name="李", family_name="四", email="lisi@example.com", phone="+86 13800138000")

功能：添加新的联系人到 Google Contacts。 参数：

• given_name：联系人的名字
• family_name（可选）：姓氏
• email（可选）：邮箱地址
• phone（可选）：电话号码

4. 更新联系人信息 (update_contact)

# 修改现有联系人的信息。
update_contact(resource_name="people/12345678901234567", email="new@example.com")

功能：修改现有联系人的信息。 参数：

• resource_name：联系人资源 ID（people/*）
• given_name（可选）：更新的名字
• family_name（可选）：更新的姓氏
• email（可选）：更新的邮箱地址
• phone（可选）：更新的电话号码

5. 删除联系人 (delete_contact)

# 从Google Contacts中删除指定的联系人。
delete_contact(resource_name="people/12345678901234567")

功能：从 Google Contacts 中删除指定的联系人。 参数：

• resource_name：要删除的联系人资源 ID（people/*）

6. 搜索联系人 (search_contacts)

# 根据指定条件搜索联系人。
search_contacts(query="王五")

功能：根据指定条件搜索联系人。 参数：

• query：搜索关键字

7. 查询 Google Workspace 目录 (search_directory)

# 在组织的Google Workspace目录中搜索用户。
search_directory(query="Marketing")

功能：在组织的 Google Workspace 目录中搜索用户。 参数：

• query：搜索关键字

8. 查看其他联系人 (view_other_contacts)

# 查看与你互动过但未添加到联系人列表的人。
view_other_contacts()

功能：查看与你互动过但未添加到联系人列表的人。

📚 详细文档

权限

使用此工具需要以下权限：

• 读写权限：
  • https://www.googleapis.com/auth/contacts.readonly
  • https://www.googleapis.com/auth/contacts.write
• 目录访问权限：
  • https://www.googleapis.com/auth/admin.directory.readonly

故障排除

常见问题及解决方法：

1. 无法获取联系人：检查 API 密钥是否正确，确保已启用 Contacts API 和 Directory API。
2. 权限被拒绝：确认应用的 OAuth scopes 已正确设置，并获得必要的授权。
3. 性能问题：优化查询条件，限制返回结果数。

贡献

欢迎社区参与开发：

• 提交 Issue 报告问题
• Fork 代码库并提交 Pull Request
• 贡献文档和翻译

仓库地址：[GitHub 链接]

📄 许可证

本项目遵循 MIT 许可证，具体内容如下：

MIT License

Copyright (c) 2023 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

如需进一步了解，请参考[官方文档]。