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.

如需進一步瞭解，請參考[官方文檔]。