google-chat-mcp

google-chat-mcp

Google Chat を MCP ツールとして利用できます。スペース、DM、サイドバーの内容を読み取り、検索し、書き込めます。

MCP over stdio に対応する単一の Go バイナリです。クライアントのサブプロセスとして、お使いのマシン上で、お使いの Google アカウントを使って実行されます。ホストするサーバーも、共有デプロイも、サービスアカウントも不要です。Google OAuth クライアントを作成して一度ログインすれば、リフレッシュトークンは OS のキーリングに保存されます。Claude Code、Claude Desktop、その他の MCP クライアントから利用できます。

google-chat-mcp を選ぶ理由

チャット連携は通常アプリとして動作します。ボットとして投稿し、誰かが追加したスペースしか参照できず、管理者が用意するサービスアカウントが必要です。このツールはあなた自身として実行されます。あなたのアカウントでアクセスできるものにアクセスし、送信したメッセージも、あなたの名前を冠したアプリではなく、あなた自身から送られます。

また、アプリの ID ではまったくアクセスできない、Chat のユーザー単位の機能も利用できます。サイドバーのセクション、スペースやスレッドの既読位置、在席状況とカスタムステータス、組織独自のカスタム絵文字などです。58 個のツールでこれらをカバーし、書き込み操作の多くは dry_run に対応しています。また、ログイン時に要求されるのは、実際に使用するツールに必要なスコープだけです。

インストール

go install github.com/mmedum/google-chat-mcp/v8/cmd/google-chat-mcp@latest

または、最新リリースから署名済みアーカイブをダウンロードしてください。amd64 と arm64 に対応した Linux、macOS、Windows 用があります。実行前に検証してください。

sha256sum -c checksums.txt --ignore-missing

# The checksum file is signed with a keyless Sigstore certificate tied to
# the release workflow's identity. The bundle carries both.
cosign verify-blob checksums.txt \
  --bundle checksums.txt.bundle \
  --certificate-identity-regexp 'https://github\.com/mmedum/google-chat-mcp/' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# And the archive itself carries build provenance.
gh attestation verify google-chat-mcp_*.tar.gz --repo mmedum/google-chat-mcp

各アーカイブには SBOM も含まれているため、自分でビルドしていないバイナリの内容を確認できます。

Claude Desktop

各リリースには .mcpb バンドルも含まれています。これを開くと Claude Desktop がサーバーをインストールし、設定ファイルに記述する項目を尋ねます。ファイルを編集する必要はありません。設定項目は、空欄のままにして記録済みの login を使うこともできる OAuth クライアント JSON、プロファイル、読み取り専用モード、ツールセット、添付ファイルのフォルダーです。取り消せない操作を行うツール（enable_destructive）は有効にしない限りオフのままです。また、フォルダーを選ぶまでは添付ファイルの転送もオフです。このサーバーは、呼び出しの前に確認を求めません。Claude Desktop が各ツールを承認します。また、常に許可したツールは確認なしで実行されるため、そのツールが必要でない限り enable_destructive はオフのままにしてください。

各アーキテクチャの macOS、Windows、Linux に対応しています。macOS ではユニバーサルバイナリ、Windows では amd64、Linux では起動時に適切なバイナリを選ぶ小型ランチャーを使用します。バンドルマニフェストにはアーキテクチャを指定するキーがないためです。SHA-256 は、同じ署名済みの checksums.txt に記載されています。このリリースは MCP レジストリに io.github.mmedum/google-chat-mcp として登録されています。

このバンドルではログインできません。バイナリもインストールし、google-chat-mcp login を一度実行してください。バンドルは同じ認証情報を使用します。Claude Code は .mcpb ファイルをインストールしないため、以下のコマンドを使用します。

Google をセットアップする

独自の OAuth クライアントが必要です。初回は 15 分ほどかかりますが、 docs/gcp-setup.md で手順を説明しています。概要は次のとおりです。 プロジェクトを作成し、Google Chat API、People API、Cloud Identity API を有効にして、 このサーバーが要求するスコープを使って同意画面を設定し、 デスクトップアプリ タイプの OAuth 2.0 クライアント ID を作成します。JSON をダウンロードしてください。

次に、ログインします。

google-chat-mcp login --client-secret ./client_secret.json

ログインするとブラウザーが開きます。ブラウザーを開けない場合は URL が表示されます（--no-browser を指定すると強制的にこの動作になります）。コールバックは PKCE と state を使用し、ランダムなポートで 127.0.0.1 に送られます。更新トークンは OS のキーリングに保存されます。キーリングがない場合は 0600 のファイルに保存され、その旨がコマンドに表示されます。Windows では Go のファイルモードは読み取り専用属性しか設定しないため、ファイルを保護するのはモードではなく、そのディレクトリから継承される ACL です。

google-chat-mcp status を実行すると、サインイン中のアカウントとトークンの保存先が表示されます。google-chat-mcp logout を実行すると、Google でトークンを失効させ、ローカルのコピーを削除します。

google-chat-mcp status --json は、起動前にこのサーバーが認証済みかどうかを確認する必要があるスクリプト向けに、同じ状態を 1 つの JSON オブジェクトとして標準出力に表示します。分岐には credentials.resolved を使用します。credentials.signed_in によって「まだプロファイルがない」状態と「プロファイルはあるがトークンがない」状態を区別できます。schema_version が変わるのは、フィールドが削除されるか意味が変わる場合だけです。また、アカウントはテキスト出力と同じようにドメインまでマスキングされます。人向けの出力に表示されるラベルは、どのリリースでも自由に変更できますが、オブジェクトの形式は変わりません。

SSH 経由でログインする

コールバックは リモート ホストのループバックアドレスに送られますが、ブラウザーはローカルにあるため、ポートを転送してください。ポートはランダムに選ばれ、ログイン待機中になってから一度だけ表示されるため、表示された URL から読み取ります。127.0.0.1%3A<port> のようにパーセントエンコードされています。2 つ目のローカル端末で次を実行します。

ssh -N -L <port>:127.0.0.1:<port> user@remote-host

次に、ローカルで URL を開きます。ssh が bind: Address already in use を報告した場合は、Ctrl-C でログインをキャンセルして、別のポートが選ばれるように再実行してください。

クライアントを接続する

Claude Code：

claude mcp add google-chat -- google-chat-mcp

または、クライアントの設定ファイルに次を記述します。

{
  "mcpServers": {
    "google-chat": {
      "command": "google-chat-mcp"
    }
  }
}

Claude Desktop は、独自の設定ファイルから同じ形式を読み込みます。バイナリがアプリの PATH にない場合は、バイナリの絶対パスを指定してください。または、上記の .mcpb バンドルをインストールすれば、編集は不要です。

すべての設定は環境変数で、docs/configuration.md に一覧があります。まず知っておくべき 4 つは次のとおりです。GCM_READ_ONLY=true を設定すると、Chat の内容を変更するすべてのツールが除外されます。GCM_ENABLE_DESTRUCTIVE=true を設定すると、取り消せない操作を行うツールが追加されます。GCM_PROFILE を使うと、1 台のマシンで仕事用アカウントと個人用アカウントを使い分けられます。GCM_LOCAL_DIR には、ファイルの読み書きを許可するディレクトリを指定します。最後の設定がない場合、サーバーはファイルに一切触れず、ファイルを移動する 3 つのツールはその旨を伝えます。

ツール

ツール	機能	スコープ
whoami	保存された認証情報がどのアカウントのものかを確認します	openid email profile
list_spaces	参加しているスペース、グループチャット、ダイレクトメッセージを一覧表示します	chat.spaces.readonly
get_space	リソース名で指定したスペースを取得します	chat.spaces.readonly
search_spaces	表示名で、参加している名前付きスペースを検索します。use_admin_access を指定すると、すべてのスペースが対象になります	chat.spaces.readonly；use_admin_access には chat.admin.spaces.readonly
find_group_chats	指定した人々と自分だけが参加しているグループチャットを検索します	chat.memberships.readonly, chat.spaces.readonly
find_direct_message	1 人とのダイレクトメッセージを取得します。まだ存在しない場合は作成します	chat.spaces.readonly, chat.spaces.create
get_messages	スペースの最近のメッセージを新しい順に取得し、送信者を名前に解決します	chat.messages.readonly
get_message	1 件のメッセージと、そのリアクション数、テキスト内のリンク先、引用元を取得します	chat.messages.readonly
get_thread	スレッド内のすべてのメッセージを古い順に取得します	chat.messages.readonly
download_attachment	メッセージの添付ファイルをサーバーのローカルディレクトリに保存します	chat.messages.readonly
search_messages	表示可能なすべてのスペースを対象に Google の検索を行うか、1 つのスペースを正規表現でスキャンします	chat.messages.readonly；unread_only には chat.users.readstate.readonly；space_type と space_name には chat.spaces.readonly
search_people	ディレクトリと連絡先から名前をメールアドレスに変換します	directory.readonly, contacts.readonly
find_group	Google グループのメールアドレスを、add_member が受け取る ID に変換します	cloud-identity.groups.readonly
list_members	スペースの参加者を一覧表示します。人やグループを名前とアドレスに解決し、指定すると各グループの参加者も表示します	chat.memberships.readonly, directory.readonly, cloud-identity.groups.readonly
get_member	1 件のメンバーシップについて、対象、役割、参加済みかどうかを取得します	chat.memberships.readonly, directory.readonly, cloud-identity.groups.readonly
update_member_role	管理者を通常のメンバーに戻します	chat.memberships
promote_member	GCM_ENABLE_DESTRUCTIVE を指定して、メンバーを管理者または副管理者にします	chat.memberships
list_reactions	メッセージへのリアクションを一覧表示します	chat.messages.readonly
list_pinned_messages	スペースにピン留めされている内容を取得します	chat.spaces.pins.readonly
pin_message	メッセージをピン留めします。スペースの全員に表示されます	chat.spaces.pins
unpin_message	ピン留めを解除します	chat.spaces.pins
get_space_read_state	スペースをどこまで読んだかを取得します	chat.users.readstate.readonly
get_thread_read_state	スレッドをどこまで読んだかを取得します	chat.users.readstate.readonly
mark_space_read	自分に対してのみ、スペースの未読バッジを消します	chat.users.readstate
mark_space_unread	自分に対してのみ、既読位置を戻します	chat.users.readstate
list_space_events	過去 28 日間にスペースで起きた変更を一覧表示します	要求した各イベントタイプの読み取りスコープ
get_space_event	リソース名で指定した変更を取得します	chat.spaces.readonly
get_space_notification_setting	Chat がスペースについて通知する方法を取得します。GCM_READ_ONLY の対象外です	chat.users.spacesettings
update_space_notification_setting	設定を変更するか、スペースをミュートします	chat.users.spacesettings
get_availability	自分のプレゼンスとカスタムステータスを取得します	chat.users.availability.readonly
set_availability	指定した時刻まで、アクティブ、離席中、またはサイレントモードに設定します	chat.users.availability
set_custom_status	名前の横に表示するテキストと絵文字を設定または解除します	chat.users.availability
list_custom_emojis	組織独自の絵文字を一覧表示します	chat.customemojis.readonly
get_custom_emoji	リソース名で指定した絵文字を取得します	chat.customemojis.readonly
create_custom_emoji	ローカル画像からカスタム絵文字を追加します	chat.customemojis
delete_custom_emoji	GCM_ENABLE_DESTRUCTIVE を指定して、全員からカスタム絵文字を削除します	chat.customemojis
delete_space	GCM_ENABLE_DESTRUCTIVE を指定して、スペースとその中のすべてを削除します	chat.delete
list_sections	自分のサイドバーセクションを一覧表示します	chat.users.sections.readonly
list_section_items	セクションに含まれる内容、またはスペースが属するセクションを取得します	chat.users.sections.readonly
send_message	Chat の構文または Markdown で、指定どおりのテキストを投稿します。スレッドへの投稿、メッセージの引用、アップロードしたファイルの添付もできます	chat.messages.create；引用には chat.messages.readonly
upload_attachment	ローカルファイルをスペースに送信し、添付に使うトークンを取得します	chat.messages.create
update_message	自分が送信したメッセージのテキストを編集します	chat.messages
delete_message	GCM_ENABLE_DESTRUCTIVE を指定して、メッセージを 1 件削除します。すでに削除済みの場合も成功として扱います	chat.messages
delete_thread	GCM_ENABLE_DESTRUCTIVE を指定して、スレッドの最初のメッセージとすべての返信を削除します	chat.messages
add_reaction	Unicode 絵文字でメッセージにリアクションします	chat.messages.reactions
remove_reaction	リソース名、またはメッセージ、絵文字、ユーザーを指定してリアクションを削除します	chat.messages.reactions
create_group_chat	2～20 人で名前のないグループチャットを開始します	chat.spaces.create
create_space	最大 20 人の参加者がいる非公開の名前付きスペースを作成します	chat.spaces.create
update_space	スペースの名前や説明を変更するか、非公開にします	chat.spaces
set_space_audience	GCM_ENABLE_DESTRUCTIVE を指定して、対象ユーザーにスペースを公開します	chat.spaces
add_member	メールアドレスで組織内のユーザーをスペースに招待するか、組織外のユーザーを受け入れないスペースに Google グループを追加します	chat.memberships；アドレスの確認には chat.spaces.readonly, directory.readonly
add_external_member	GCM_ENABLE_DESTRUCTIVE を指定して、組織外のユーザーを招待するか、組織外のユーザーを受け入れるスペースに Google グループを追加します	chat.memberships；グループのアドレス確認には cloud-identity.groups.readonly
remove_member	GCM_ENABLE_DESTRUCTIVE を指定して、メンバーシップを削除します。すでに削除済みの場合も成功として扱います	chat.memberships
create_section	サイドバーセクションを追加します	chat.users.sections
rename_section	サイドバーセクションの名前を変更します	chat.users.sections
delete_section	GCM_ENABLE_DESTRUCTIVE を指定して、サイドバーセクションを削除します。所属するスペースはデフォルトに戻ります	chat.users.sections
position_section	絶対順位を指定するか、先頭または末尾に移動してセクションの順序を変更します	chat.users.sections
move_space_to_section	スペースをセクションに整理します。すでにそのセクションにあるスペースはそのままです	chat.users.sections
セクションは自分専用のサイドバーです。そこに何を追加してもスペースに変更はなく、ほかの人に見られることもありません。

リソースをコンテキストに含めるクライアント向けに、対応するツールと同じ内容を持つリソースが3つあります。

• gchat://spaces/{space_id}
• gchat://spaces/{space_id}/messages/{message_id}
• gchat://spaces/{space_id}/threads/{thread_id}

安全性

• 29個の書き込みツールでdry_runを使用できます。 送信されるはずだったリクエスト本文が返され、呼び出しによって書き込みが行われることはありません。このフラグにより、HTTPクライアントが書き込みを拒否するコンテキストでリクエストが実行されるため、独自のプレビュー分岐を実装し忘れたツールは、投稿する代わりにエラーになります。プレビューで表示または確認する内容（引用対象のメッセージや、削除を繰り返すテキストなど）は、読み取られる場合があります。

• GCM_READ_ONLY=trueにすると、書き込みツールは登録されません。 登録されていないツールは、クライアントの権限モードやモデルの要求にかかわらず呼び出せません。この設定はサーバーの起動時に指定するため、1回の呼び出しではなくセッション全体に適用されます。有効にした状態でgoogle-chat-mcp loginを実行すると、読み取り専用のスコープが要求され、そのトークンでも書き込みはできません。以前のログインで取得したトークンは、再度ログインするまで書き込みスコープを保持します。また、書き込みを再び有効にする場合も、再度ログインする必要があります。

• 取り消せない操作は、明示的に有効にしない限り登録されません。 削除操作、delete_thread、set_space_audience、promote_member、add_external_memberは、GCM_ENABLE_DESTRUCTIVE=trueの場合にのみ利用できます。その場合、各呼び出しでconfirm: trueを指定します。delete_message、delete_thread、delete_space、delete_custom_emoji、set_space_audienceでは、操作対象も繰り返し指定します。メッセージの冒頭部分、またはスペース名や絵文字名などです。サーバーはまず対象を読み取り、内容が異なる場合は[stale]として拒否します。そのため、クライアントに表示される呼び出しから、どのメッセージやスペースが対象なのかがわかります。

• 各呼び出しを承認するのはクライアントです。サーバーから確認を求めることはありません。 Claude Codeでは、permissions.askに指定したツールの呼び出しが確認されます。claude.aiとCodexでは、destructiveHintが付いたツールの呼び出し時に確認が表示されます。上記の一覧でGCM_ENABLE_DESTRUCTIVEが必要なツールには、すべてこのマークが付いています。VS Codeでは、download_attachmentを含め、変更を行うすべてのツールの呼び出し時に確認が表示されます。Claude Codeでは、投稿、招待、共有、削除を行う書き込みツールを設定のpermissions.askに指定します。その際、google-chatの代わりにサーバーに付けた名前を使用してください。

  {
    "permissions": {
      "ask": [
        "mcp__google-chat__send_message", "mcp__google-chat__update_message",
        "mcp__google-chat__upload_attachment",
        "mcp__google-chat__create_space", "mcp__google-chat__create_group_chat",
        "mcp__google-chat__find_direct_message",
        "mcp__google-chat__add_member", "mcp__google-chat__add_external_member",
        "mcp__google-chat__update_member_role", "mcp__google-chat__promote_member",
        "mcp__google-chat__remove_member", "mcp__google-chat__update_space",
        "mcp__google-chat__pin_message", "mcp__google-chat__create_custom_emoji",
        "mcp__google-chat__delete_message", "mcp__google-chat__delete_thread",
        "mcp__google-chat__delete_section"
      ]
    }
  }
  

  delete_space、set_space_audience、delete_custom_emojiにはルールが必要ありません。これらにはClaude CodeのrequiresUserInteractionマークが付いているため、Claude Code 2.1.199以降では、すべてのインタラクティブモードで呼び出しごとに確認が求められ、確認を求められない環境では呼び出しが拒否されます。

• 既定では、スペース全体やスペース外にまで届くことはありません。 全員を示す<users/all>を含む投稿や編集は拒否されます。スペースは非公開で作成され、update_spaceによって公開されることもありません。組織外のユーザーを受け入れるスペースでは、add_memberは組織のディレクトリに登録されていないアドレスとGoogleグループを拒否します。また、update_member_roleで誰かがマネージャーになることもありません。その場合はadd_external_memberとpromote_memberを使用します。

• send_messageは本文をそのまま投稿します。 前後に文言を付け加えたり、「アシスタントが送信しました」というフッターを付けたりしません。

• 投稿の再試行によって、同じ内容が二重に投稿されることはありません。 各メッセージにはクライアントが選んだIDが付与されるため、タイムアウト後に再試行すると、再度投稿する代わりに、すでに投稿された内容が返されます。

• ログにペイロードが記録されることはありません。 どの呼び出しがどのリソースに対して行われ、どのように終了したかを記録します。メッセージ本文、アドレス、名前、検索語句は記録されず、これらが含まれている場合にビルドが失敗するテストもあります。

仕組み

MCP client ──stdio──► google-chat-mcp
                       ├── tools      one handler per tool; shapes the reply
                       ├── service    the rules: idempotency, degrading, search
                       ├── gchat      REST client for Chat, People and OIDC
                       ├── directory  email cache, so a page of messages costs one lookup
                       └── auth       refresh token → access token

すべてのスペース、メッセージ、スレッドは位置ではなくリソース名で指定されます。Googleがトークンを返す間は、一覧の取得でページ送りが続けられます。Chatはフィルターを適用する前にページサイズを適用するため、空のページが返された後も処理が続きます。

ヘルプの利用

問題が発生した場合は、google-chat-mcp doctor を実行してください。認証情報、付与されたスコープ、Google からの実際の応答を確認し、不足しているものを示します。初回実行時に起こる問題のほとんどは、API が有効になっていないか、同意画面にご自身が登録されていないことが原因です。

それでも原因がわからない場合は、 issue を作成してください。issue にスペースやメッセージのリソース名、メッセージ本文、 client_secret.json、トークンを貼り付けないでください。代わりに、どのような状態かを説明してください。 セキュリティ上の問題は、非公開で SECURITY.md に記載された方法で報告してください。

バージョン管理

ツール名と出力フィールドは、メジャーバージョン内では安定しています。新しいスコープ、別のログイン、クライアント設定でのコマンド変更など、対応が必要な変更には CHANGELOG.md で Breaking: と記載します。各リリースのノートも、このファイルをもとに作成されます。

開発

make build     # the binary
make test      # race detector, coverage floor
make check     # everything CI runs

make check の成功が完了の基準です。フォーマット、go vet、 golangci-lint、パッケージごとのカバレッジ基準を設けたレーステスト、 govulncheck、ライセンスチェック、stdio スモークテスト、リリース済みのツール仕様とのスキーマ差分チェック、Google API のメソッドに判定がない場合や、このサーバーが実行する呼び出しに対応する行がない場合に失敗する API カバレッジゲート、さらに README、ドキュメント、変更履歴がコードと乖離している場合に失敗する陳腐化チェックが行われます。

ドキュメント

• docs/architecture.md — リクエストの流れ、パッケージ構成、規約の根拠となる記録、コントリビューターが覆すべきでない設計上の判断。
• docs/configuration.md — すべての環境変数。
• docs/gcp-setup.md — Google Cloud プロジェクトと OAuth クライアントの設定手順。
• docs/security.md — 脅威モデル。
• docs/runbook.md — 認証情報のローテーションまたは復旧方法。

コントリビューション

質問やバグは issue に投稿してください。プルリクエストも歓迎します。ブランチとレビューの流れについては CONTRIBUTING.md をご覧ください。また、make check に合格する必要があります。

セキュリティ

脆弱性の報告方法については SECURITY.md をご覧ください。

行動規範

CODE_OF_CONDUCT.md — Contributor Covenant 3.0。

ライセンス

Apache 2.0 — LICENSE をご覧ください。