MCP Google Contacts Server

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

Google コンタクトの機能を提供する Machine Conversation Protocol（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 をインストールします。
   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 : アカウントの有効なリフレッシュトークン

🛠️ 使用方法

🏃‍♂️ 基本的な起動

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

⚙️ コマンドライン引数

📝 例

HTTP トランスポートから開始します。

特定の資格情報ファイルを使用:

資格情報を直接提供します:

🔌 MCPクライアントとの統合

このサーバーを MCP クライアント (Anthropic の Claude with Cline など) で使用するには、MCP 構成に追加します。

🧰 利用可能なツール

この MCP サーバーは次のツールを提供します。

🔍 詳細なツールの説明

📋 list_contacts

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

パラメータ:

• name_filter (オプション): 名前で連絡先をフィルタリングする文字列
• max_results （オプション）：返される連絡先の最大数（デフォルト：100）

例：

👤 get_contact

特定の連絡先に関する詳細情報を取得します。

パラメータ:

• identifier : リソース名 (people/*) または連絡先のメールアドレス

例：

➕ create_contact

Google 連絡先に新しい連絡先を作成します。

パラメータ:

• given_name : 連絡先の名
• family_name （オプション）: 連絡先の姓
• email （オプション）: 連絡先のメールアドレス
• phone （オプション）: 連絡先の電話番号

例：

✏️ update_contact

既存の連絡先を新しい情報で更新します。

パラメータ:

• resource_name : 連絡先リソース名 (people/*)
• given_name （オプション）: 更新された名
• family_name （オプション）: 更新された姓
• email （オプション）: 更新されたメールアドレス
• phone （オプション）：更新された電話番号

例：

🗑️ delete_contact

Google 連絡先から連絡先を削除します。

パラメータ:

• resource_name : 削除する連絡先リソース名（people/*）

例：

🔍 search_contacts

名前、メールアドレス、電話番号で連絡先を検索します。

パラメータ:

• query : 連絡先で検索する検索語
• max_results (オプション): 返される結果の最大数 (デフォルト: 10)

例：

🏢 list_workspace_users

組織のディレクトリ内の Google Workspace ユーザーを一覧表示します。

パラメータ:

• query （オプション）: 特定のユーザーを見つけるための検索語
• max_results (オプション): 返される結果の最大数 (デフォルト: 50)

例：

🔭 search_directory

組織の Google Workspace ディレクトリを対象に検索を実行します。

パラメータ:

• query : 特定のディレクトリメンバーを見つけるための検索語
• max_results (オプション): 返される結果の最大数 (デフォルト: 20)

例：

👥 get_other_contacts

「その他の連絡先」セクションから連絡先を取得します。これは、やり取りしたことがあるものの、連絡先に追加していない人々です。

パラメータ:

• max_results (オプション): 返される結果の最大数 (デフォルト: 50)

例：

🔒 権限

サーバーを初めて起動する際は、Googleで認証し、連絡先へのアクセスに必要な権限を付与する必要があります。認証フローが、このプロセスを案内します。

❓ トラブルシューティング

• 🔐 認証の問題: 資格情報が有効であり、必要なスコープがあることを確認してください
• ⚠️ API の制限: Google People API の割り当て制限に注意してください
• 📝 ログ: コンソール出力でエラーメッセージとデバッグ情報を確認します

👥 貢献する

貢献を歓迎します！お気軽にプルリクエストを送信してください。

📄 ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。