Google Contacts MCP

Google Contacts MCP

英語 | ロシア語

A1 Google Contacts MCP を使うと、AI アプリから自然な言葉で Google のアドレス帳を管理できます。連絡先の検索、新規作成や更新、ラベルを使った整理、一括インポートやクリーンアップの実行、自動保存された「その他の連絡先」を実際の連絡先に変換できます。

Google Contacts を支える API である Google People API を、Google アカウントで利用します。すべての更新を同時編集から保護し、明示的なフィールドマスクで読み取り内容を簡潔に保ち、連絡先のあらゆる作業が可能であるかのように見せるのではなく、People API の制限を明確に示します。

• 25 個のツール。 連絡先の一覧表示、検索、読み取り、個別または一括での作成、更新、削除、連絡先グループとメンバーシップの管理、「その他の連絡先」へのアクセスができます。
• 会話から接続できます。 「Google Contacts に接続して」と伝えると、サーバーが OAuth クライアントの設定を案内し、PKCE を使用して 127.0.0.1 への Google のリダイレクトを受け取り、トークンを自身で保持します。設定ファイルも再起動も必要ありません。
• 更新で既存の内容を上書きしません。 すべての更新で etag による保護を行います。連絡先を読み取った後に別の場所で変更されていた場合、同時編集を黙って上書きせず、書き込みは失敗します。
• 削除は取り消せません。 People API にゴミ箱機能はありません。連絡先やグループを削除すると完全に消去され、サーバーは該当ツールを破壊的操作として示すため、AI アプリは事前に確認できます。
• Google のスコープは最小限です。 読み取りと書き込みには contacts を使用します。読み取り専用の設定なら contacts.readonly で十分です。「その他の連絡先」には contacts.other.readonly のみを使用し、アカウント全体への広範なアクセスは行いません。

まずは読み取り専用の質問から始めましょう。

連絡先から Acme 関係者を全員見つけて、メールアドレスと電話番号を表示してください。

サーバーに接続する · ユースケースを見る · 技術ドキュメントを開く

1 分で動作を確認

あなた： Jane Doe の連絡先カードを表示してください。メールアドレス、電話番号、会社名をお願いします。

アシスタント： 連絡先を見つけ、指定されたフィールドを表示します。変更はありません。

あなた： 電話番号を +1 415 555 0100 に変更して、「Clients」ラベルに追加してください。

アシスタント： 連絡先と変更案を表示してから、書き込み前に確認を求めます。

あなた： 確認します。

アシスタント： etag による保護付きの更新とラベルの追加を適用します。その間に別の場所で連絡先が変更されていた場合、上書きせずに書き込みは失敗します。

目次

• クイックスタート
• できること
• 連絡先の変更方法
• 変更できる内容
• アクセスの取得
• 設定
• データ、制限、バックグラウンド処理
• 技術ドキュメント
• サポート

クイックスタート

Node.js 20 以降と Google アカウントが必要です。インストール時に認証情報は必要ありません。サーバーは会話中に接続します。

1. サーバーを AI アプリに追加します。
2. 「Google Contacts に接続して」と伝えると、アシスタントが設定ファイルを編集することなく、OAuth クライアントの作成とアクセスの承認を案内します。
3. 上記の読み取り専用の質問をします。

codex mcp add google-contacts \
  -- npx -y mcp-google-contacts@latest

codex mcp list

claude mcp add \
  --transport stdio --scope user google-contacts \
  -- npx -y mcp-google-contacts@latest

claude mcp list

{
  "mcpServers": {
    "google-contacts": {
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

{
  "mcpServers": {
    "google-contacts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

{
  "servers": {
    "google-contacts": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-google-contacts@latest"]
    }
  }
}

できること

連絡先の検索と確認

• Acme の全員を検索し、メールアドレスと電話番号を表示してください。
• 「Clients」ラベルに登録されている人を表示してください。
• 前回の同期以降に変更された連絡先を一覧表示してください。

アドレス帳を最新の状態に保つ

• Jane Doe の連絡先を、メールアドレス、電話番号、会社名とともに作成してください。
• 連絡先の電話番号や役職を更新してください。
• 50 人分を一括でインポートするか、古くなった連絡先を 1 回の呼び出しで削除してください。

ラベルで整理

• 「Clients」ラベルを作成し、これらの連絡先を追加してください。
• ラベルの名前を変更するか、連絡先を別のラベルに移動してください。
• 連絡先は削除せずにラベルを削除してください。または、明示的に依頼した場合に限り、連絡先と一緒に削除してください。

「その他の連絡先」の操作

• Google が自動保存した、自分の連絡先には登録されていないアドレスを表示してください。
• そのうち 1 件を、実際の連絡先として「My Contacts」にコピーしてください。

連絡先の変更について

1. すべての連絡先、グループ、その他の連絡先には完全なリソース名（people/c...、contactGroups/...、otherContacts/...）があり、ツールは API が返すものとまったく同じ名前でレコードを指定します。
2. 読み取りでは、フィールドマスクで指定されたフィールドのみが返されます（デフォルト：名前、メールアドレス、電話番号、組織、グループへの所属）。フィールドが見当たらなくても、単にマスクの対象外である可能性があります。
3. 更新では、指定したフィールドグループがそれぞれ全体として置き換えられ、etagで保護されます。読み取り後に連絡先が別の場所で変更されていた場合、同時に行われた編集を上書きせず、書き込みは失敗します。
4. 削除は取り消せません。People API にゴミ箱や元に戻す機能はありません。

検索対象は、直近の書き込みが反映されるまで数秒遅れることがあるキャッシュで、結果は最大30件です。「その他の連絡先」— Google が自動的に保存するアドレス — は、読み取りや「マイコンタクト」へのコピーのみ可能で、その場で編集することはできません。連絡先の写真に専用ツールはありませんが、raw_request から該当するエンドポイントにアクセスできます。

変更できる内容

確認プロンプトは AI クライアントが制御します。サーバーは読み取り、書き込み、破壊的なツールを識別できるようにマークするため、クライアントは内容の確認と実際の変更を区別できます。

アクセスの取得

Google Contacts には OAuth 2.0 が必要です。API キーだけでは利用できません。接続方法は2つあり、1つ目は設定ファイルが不要です。

チャットから接続する（推奨）

「Google Contacts に接続して」と伝えると、アシスタントが手順を案内します。

1. setup_instructions でチェックリストが表示されます。Google Cloud プロジェクトを作成または選択し、Google People API を有効にして、同意画面を設定し、デスクトップアプリの OAuth クライアントを作成します。
2. そのクライアントの JSON（「Download JSON」）をダウンロードし、アシスタントにそのパスを伝えます。set_client が所有者のみアクセスできる形で保存します。シークレットが会話を通じて送信されることはありません。
3. start_login から Google の同意リンクが返されます。このマシン上でリンクを開いて承認すると、コードが 127.0.0.1 上の1回限りのリスナーに返されます（PKCE）。チャットを経由することはありません。
4. finish_login がコードを交換し、トークンを ~/.config/mcp-google-contacts/credentials.json（モード 0600）に保存して、実際に Google People API を呼び出して認証情報を検証します。そのため、API がまだ有効になっていない場合も、その場で検出できます。

トークンは呼び出しのたびに再読み込みされるため、AI アプリを再起動せずにすぐ接続できます。auth_status で接続状況を確認でき、logout で認証を取り消して認証情報を削除できます。

環境変数（CI、無人インストール）

1. Google Cloud プロジェクトを作成または選択し、People API を有効にします。

2. OAuth 同意画面を設定し、Desktop app OAuth クライアントを作成します。

3. 管理する連絡先が登録されている Google アカウントを認証します。OAuth 2.0 Playground では、Use your own OAuth credentials を有効にすると、リフレッシュトークンを取得できます。

4. 使用する機能に必要な最小限のスコープをリクエストします。

   https://www.googleapis.com/auth/contacts
   https://www.googleapis.com/auth/contacts.other.readonly
   

contacts は連絡先とグループの読み取りおよび書き込みに対応しています。読み取り専用の構成では contacts.readonly だけで十分です。contacts.other.readonly は「Other contacts」ツールを使う場合にのみ必要です。特定のツールで 403 が発生する場合、通常はそのツールに必要なスコープを指定せずにリフレッシュトークンを発行したことが原因です。不足しているスコープを追加して、再度同意してください。

テストモードの OAuth リフレッシュトークンは、7 日後に期限切れになることがあります。長期間アクセスする必要がある場合は、OAuth アプリを公開するか、Workspace ドメインの内部アプリを使用してください。クライアントシークレットとリフレッシュトークンはパスワードとして扱ってください。

設定

すべての変数は省略可能です。どの変数も設定しない場合、サーバーはチャットから接続します。

* OAuth 3 点セット、またはアクセストークンのいずれかを指定してください。認証情報を一切指定しなくてもサーバーは起動して MCP ハンドシェイクを完了しますが、最初のツール呼び出し時に設定が必要な変数名が正確に表示されます。

データ、制限、バックグラウンド処理

• リクエストは Google に送信されます。 ローカルサーバーは Google OAuth トークンを更新し、people.googleapis.com の People API を呼び出します。匿名のテレメトリには、インストール ID、パッケージバージョン、AI クライアントとプラットフォームのバージョン、ツール名が含まれます。OAuth トークン、連絡先データ、ツールの引数、プロンプトは含まれません。オプトアウトするには ASKADS_TELEMETRY=0 を設定してください。
• Google のクォータはユーザーごとに設定されており、上限は低めです。 People API のデフォルトクォータでは、ユーザーあたり毎分約 90 回の読み取りと 90 回の書き込みが許可されています。そのため、単一の呼び出しを繰り返すよりもバッチツールの利用が適しています。変更を伴うバッチは一度に 1 つずつ実行する必要があります。429 が発生すると、サーバーは待機して再試行します。読み取りではネットワークエラーや 5xx エラーの後にも再試行しますが、不確定な失敗の後に書き込みを再実行することはありません。
• バックグラウンドでのポーリングは行いません。 サーバーは呼び出されたときにのみ実行されます。list_contacts は同期トークンに対応しているため、スケジュールタスクを備えた AI アプリでは、変更分のみを定期的に取得できます。同期トークンは約 7 日後に期限切れとなり、その後は連絡先をすべて再取得する必要があります。

技術ドキュメント

• MCP 機能カタログ — すべてのツールについて、タスク別にまとめたページです。
• すべてのツールと入力
• 開発ドキュメント
• 公開ドキュメント
• Google People API リファレンス

サポート

バグを見つけた場合や、必要な利用シナリオがある場合は、issue を作成するか、Telegram でお知らせください。

最後まで読んでいただき、ありがとうございます！