📇 MCP Google コンタクト サーバー

Google コンタクトの機能を提供する Machine Conversation Protocol（MCP）サーバー。AI アシスタントによる連絡先の管理、組織のディレクトリの検索、Google Workspace とのやり取りが可能になります。

✨ 特徴

• Google 連絡先の一覧と検索

• 連絡先の作成、更新、削除

• Google Workspace ディレクトリを検索

• 「その他の連絡先」（やり取りしたが追加していない人）を表示する

• 組織内の Google Workspace ユーザーにアクセスする

Related MCP server: Google Drive MCP Server

🚀 インストール

📋 前提条件

• Python 3.12以上

• 連絡先にアクセスできるGoogleアカウント

• People API が有効になっている Google Cloud プロジェクト

• Google API アクセス用の OAuth 2.0 認証情報

🧪 uv を使用する（推奨）

1. まだインストールしていない場合は、uv をインストールします。

   pip install uv

2. リポジトリをクローンします。

   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
   cd mcp-google-contacts-server

3. 仮想環境を作成し、依存関係をインストールします。

   uv venv
   source .venv/bin/activate
   uv pip install -r requirements.txt

📦 pip の使用

1. リポジトリをクローンします。

   git clone https://github.com/rayanzaki/mcp-google-contacts-server.git
   cd mcp-google-contacts-server

2. 依存関係をインストールします:

   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 : アカウントの有効なリフレッシュトークン

🛠️ 使用方法

🏃‍♂️ 基本的な起動

python src/main.py
# or
uv run src/main.py

これにより、デフォルトの stdio トランスポートを使用してサーバーが起動します。

⚙️ コマンドライン引数

📝 例

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 with 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

Google の連絡先をすべて一覧表示したり、名前でフィルタリングしたりします。

パラメータ:

• 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 ファイルを参照してください。