📇 MCP Google Contacts Server

📇 MCP Google Contacts Server

Google Contacts の機能を提供する Machine Conversation Protocol（MCP）サーバーです。AI アシスタントが連絡先を管理し、組織のディレクトリを検索して、Google Workspace と連携できます。Gemini CLI の Gemini AI による初期版から大幅に更新されています。

✨ 機能

• Google Contacts の連絡先を一覧表示および検索
• 連絡先の作成、更新、削除
• Google Workspace のディレクトリを検索
• 「その他の連絡先」（やり取りしたことはあるものの、追加していない相手）を表示
• 組織内の Google Workspace ユーザーにアクセス

🚀 インストール

📋 前提条件

• Python 3.12 以上
• 連絡先にアクセスできる Google アカウント
• People API が有効になっている Google Cloud プロジェクト
• Google API にアクセスするための OAuth 2.0 認証情報

📦 ソースからのインストール

mcp-google-contacts-server を Python パッケージとしてインストールするには：

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

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

2. ソースディレクトリの名前を変更します： パッケージは、ソースコードが mcp_google_contacts_server という名前のディレクトリにあることを想定しています。

   mv src mcp_google_contacts_server
   

3. パッケージをインストールします： パッケージとその依存関係がインストールされ、mcp-google-contacts コマンドが PATH から利用できるようになります。

   pip install .
   

   注意：インストール後にインポートエラーが発生した場合は、ソースファイル（main.py、tools.py、google_contacts_service.py、formatters.py、config.py）内の相対インポートが、絶対インポート（例：from mcp_google_contacts_server.module_name import ...）に更新されていることを確認してください。通常は pip install . によって自動的に処理されますが、パッケージ構成が特殊な場合は手動で調整が必要になることがあります。

🔑 認証の設定

サーバーが連絡先にアクセスするには、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：アカウントの有効なリフレッシュトークン

注意：Google OAuth クライアント ID とクライアントシークレットの既存の環境変数名が異なる場合（例：GOOGLE_OAUTH_CLIENT_ID）、サーバーが正しく読み込めるように、.env ファイル内で別名を設定できます（例：GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID）。 mcp-google-contacts の実行前に、コマンドラインで export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET などを使用します：

env | grep GOOGLE
export GOOGLE_CLIENT_ID=$GOOGLE_OAUTH_CLIENT_ID && export GOOGLE_CLIENT_SECRET=$GOOGLE_OAUTH_CLIENT_SECRET
env | grep GOOGLE
mcp-google-contacts

{authentication evocation should happen here)

🚀 初回認証（推奨）

GOOGLE_REFRESH_TOKEN を取得する初回の認証フローでは、対話型のブラウザープロンプトが表示されない可能性のある MCP クライアント上ではなく、ターミナルで mcp-google-contacts コマンドを直接実行することをおすすめします。

例：

mcp-google-contacts

ターミナルとブラウザーの指示に従って認証を完了してください。GOOGLE_REFRESH_TOKEN が表示されたら、非対話型の使用に備えて環境変数として設定できます。

🛠️ 使用方法

🏃‍♂️ 基本的な起動

python src/main.py
# or
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 トランスポートで起動します：

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 クライアント（Cline を使用する Anthropic の Claude など）で使うには、MCP 設定に追加します：

{
  "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）

例：

list_contacts(name_filter="John", max_results=10)

👤 get_contact

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

パラメーター：

• identifier：連絡先のリソース名（people/*）またはメールアドレス

例：

get_contact("[email protected]")
# or
get_contact("people/c12345678901234567")

➕ create_contact

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

パラメーター：

• given_name：連絡先の名
• family_name（任意）：連絡先の姓
• email（任意）：連絡先のメールアドレス
• phone（任意）：連絡先の電話番号

例：

create_contact(given_name="Jane", family_name="Smith", email="[email protected]", phone="+1-555-123-4567")

✏️ update_contact

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

パラメーター：

• resource_name：連絡先のリソース名（people/*）
• given_name（任意）：更新後の名
• family_name（任意）：更新後の姓
• email（任意）：更新後のメールアドレス
• phone（任意）：更新後の電話番号

例：

update_contact(resource_name="people/c12345678901234567", email="[email protected]")

🗑️ delete_contact

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

パラメーター：

• 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 のクォータ制限にご注意ください
• 📝 ログ：エラーメッセージやデバッグ情報を確認するには、コンソール出力を確認してください

👥 貢献

貢献を歓迎します！お気軽に Pull Request を送信してください。

📄 ライセンス

このプロジェクトは MIT ライセンスのもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。