Google Contacts

google-contacts-mcp

Google Contacts 用の MCP サーバーです。連絡先の一覧表示、検索、管理ができます。

ユースケース

メールアドレスの検索：「届いたばかりの最新の JIRA チケットを確認してください。セキュリティチームの Sarah に意見を聞くため、メールを送れますか？」→ Sarah のメールアドレスを見つけ、メッセージの下書きを作成します。

名刺の登録：ネットワーキングイベントの後、名刺の写真を撮ると、アシスタントが情報を抽出し、会った場所についてのメモを添えて連絡先に追加します。

知り合いを探す：「Google に知り合いはいますか？」または「来週ロンドンに行きます。誰に会っておくとよいですか？」→ 個人のネットワークを検索します。

電話のリマインダー：「午後3時に Mike に電話するようリマインドしてください」→ Mike の電話番号を添付したカレンダーイベントを作成するため、リマインダーからすぐに電話をかけられます。

連絡先の更新：誰かが退職し、新しい個人用メールアドレスが記載された不在通知を受け取ると、アシスタントがその人の連絡先を自動で更新します。

（これらはあくまで例です。連絡先の検索や管理が必要なワークフローであれば、どのようなものでも利用できます。）

セットアップ

1. Google OAuth 認証情報を作成する

1. Google Cloud Console にアクセスします
2. 新しいプロジェクトを作成します（または既存のプロジェクトを使用します）
3. People API を有効にします
4. APIs & Services → OAuth consent screen に移動し、同意画面を設定します
5. APIs & Services → Credentials → Create Credentials → OAuth client ID に移動します
6. Web application を選択します
7. Authorized redirect URIs に http://localhost:3000/callback を追加します
8. Client ID と Client Secret を控えておきます

2. サーバーを実行する

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

サーバーはデフォルトで http://localhost:3000 で実行されます。PORT=3001 を指定すると変更できます。

3. MCP クライアントに追加する

サーバーを実行した状態で、install-mcp の手順に従ってください。MCP クライアント（Claude Code、Claude Desktop、Cursor、Cline、VS Code など）に適した設定が生成されます。

アーキテクチャ

このサーバーは、Google への OAuth プロキシとして機能します。

graph LR
    A[MCP client] <--> B[google-contacts-mcp] <--> C[Google OAuth/API]

1. サーバーは /.well-known/oauth-authorization-server を通じて、自身を OAuth 認可サーバーとして通知します
2. /register は Google OAuth クライアント認証情報を返します
3. /authorize は、クライアントのコールバック URL を state に含めて Google にリダイレクトします
4. /callback は Google からコードを受け取り、クライアントのコールバックに転送します
5. /token はクライアント認証情報を挿入し、トークンリクエストを Google に中継します
6. /mcp は MCP リクエストを処理し、ベアラートークンを使って People API を呼び出します

このサーバーはトークンや状態を保持せず、Google への OAuth リクエストを中継するだけです。

ツール

ツール	説明
contacts_list	名前、メールアドレス、電話番号、組織、誕生日、イベント、URL、住所、ニックネーム、続柄、IM ユーザー名、性別、外部 ID、クライアントデータ、カスタムフィールドを含む連絡先の一覧を表示します
contacts_search	名前、メールアドレス、電話番号で連絡先を検索します
directory_search	組織のディレクトリから同僚を検索します
contact_get	1件の連絡先の詳細情報を取得します
contact_create	新しい連絡先を作成します
contact_update	既存の連絡先を更新します
contact_delete	連絡先を完全に削除します
contact_photo_update	連絡先の写真を設定または置き換えます
contact_photo_delete	連絡先の写真を削除します
contact_groups_list	連絡先グループ（ラベル）の一覧を表示します
contact_group_get	メンバーを含む連絡先グループを取得します
contact_group_create	新しい連絡先グループを作成します
contact_group_update	連絡先グループの名前を変更します
contact_group_delete	連絡先グループを完全に削除します
contact_group_members_modify	連絡先グループに連絡先を追加または削除します

貢献

GitHub でのプルリクエストを歓迎します。始めるには、次の手順に従ってください。

1. Git と Node.js をインストールします
2. リポジトリをクローンします
3. npm install で依存関係をインストールします
4. npm run test を実行してテストします
5. npm run build でビルドします

リリース

バージョンはセマンティックバージョニング仕様に従います。

リリースするには：

1. npm version <major | minor | patch> を使用してバージョンを更新します
2. git push --follow-tags を実行してタグとともにプッシュします
3. GitHub Actions が NPM レジストリに公開するまで待ちます。