google-chat-mcp-server

Minimal read-only Google Chat MCP server for Claude Code.

Claude Code に Google Chat のやりとりを読ませ、把握・記録させるための MCP サーバーです。

• 読み取り専用のスコープ4つだけを要求します（送信・編集・削除・既読の変更はできません）

• 外部への送信先は Google の API だけです（第三者のサーバーを経由しません）

• ツールは5つ: スペース一覧／メッセージを読む／キーワード検索／参加者／未読

同じ作者の google-sheets-mcp-server（読み取り専用の Sheets MCP）と同じ考え方で作っています。

ツール

space には、スペースの名前（一部でよい）・URL・ID（spaces/…）のどれでも渡せます。

Related MCP server: google-chat-mcp

記録のとり方と、未読との使い分け

• 記録は next_since で続きから読みます。 get_messages の返り値の next_since を記録に残し、次回はそれを since に渡すと、重複も取りこぼしもなく続きから読めます（next_since は API の時刻そのままで、小数秒まで落としません）。since を渡したときの has_more が true なら、まだ新しい分があります。

• since を渡さずに「最新 N 件」を読んだときは、has_older と older_until を見ます。 has_older が true なら、それより古い分があります。older_until を until に渡すと、さらに古い分を読めます。

• 同じ時刻のメッセージは2回の読み取りに分けません（limit を少し超えることがあります）。

• 未読は「まだ見ていない分の把握」に使います。 未読は、利用者が Chat の画面で開いた時点で（スマホで開いた分も）消えます。記録の続きの起点には使いません。

• 件数の上限で打ち切ったときは、必ず has_more / truncated / notes で知らせます。黙って切ることはしません。

セットアップ

1. Google Cloud の準備（Google Workspace のアカウントが必要）

Chat API は Google Workspace のアカウント専用です。

1. Google Cloud コンソールで、自分の Workspace の組織の中に新しいプロジェクトを作る

2. 「API とサービス」→「ライブラリ」で Google Chat API を有効にする

3. Google Chat API の 「構成」 タブで、アプリ名・説明を入れ、「インタラクティブ機能を有効にする」をオフにして保存する（読むだけでも、この登録が必要です）

4. 「Google Auth Platform」で同意画面を作る。対象は「内部」 にする

   • 「外部」でテスト中のままだと、ログインが7日で切れます（Google のドキュメント）

5. 「クライアント」→「クライアントを作成」で 「デスクトップ アプリ」 を作る。「このクライアントを AI 搭載エージェントに使用する」にチェックを入れる（MCP 連携向けの自己申告で、権限は増えません。Google のヘルプ）

6. 作成直後の画面で JSON をダウンロードし、次の場所に置く

mkdir -p ~/.config/google-chat-mcp && chmod 700 ~/.config/google-chat-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-chat-mcp/credentials.json
chmod 600 ~/.config/google-chat-mcp/credentials.json

2. インストール

git clone https://github.com/tg-tool/google-chat-mcp-server.git
cd google-chat-mcp-server
python3 -m venv .venv
.venv/bin/pip install -e .

3. ログイン（初回のみ）

.venv/bin/python -m google_chat_mcp.auth

ブラウザが開くので、Workspace のアカウントでログインし、表示される読み取りの権限をすべて許可します。トークンは ~/.config/google-chat-mcp/token.json（0600）に保存されます。

4. Claude Code に登録

claude mcp add google-chat-readonly --scope user -- /path/to/google-chat-mcp-server/.venv/bin/python -m google_chat_mcp.server
claude mcp get google-chat-readonly

保存先は環境変数 GOOGLE_CHAT_MCP_CREDENTIALS / GOOGLE_CHAT_MCP_TOKEN で変えられます。

セキュリティ

スコープは次の4つだけです。

• https://www.googleapis.com/auth/chat.spaces.readonly

• https://www.googleapis.com/auth/chat.messages.readonly

• https://www.googleapis.com/auth/chat.memberships.readonly

• https://www.googleapis.com/auth/chat.users.readstate.readonly

読み取り専用は三重に担保しています。

1. 要求するスコープが読み取り専用だけ（テストで完全一致を確認）。保存済みのトークンも、スコープがこの4つと完全に一致しなければ使いません

2. Google の API に触れるのは src/google_chat_mcp/api.py の1か所だけで、呼ぶのは list・get・getSpaceReadState だけ（テストでソースを走査して確認）

3. Google 側でも、読み取り専用のトークンでの書き込みは拒否される

認証情報とログの扱い

• 認証情報はローカルの ~/.config/google-chat-mcp/（0600）に置き、git に入れません（.gitignore 済み）

• サーバーのログは WARNING 以上だけで、メッセージの本文やスペース名をログに出しません

読んだ内容の行き先

• 読んだチャットの内容は、MCP クライアント（Claude）に渡ります。機密の扱いは、利用者の組織の規定に従ってください。

開発

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -q
.venv/bin/ruff check src tests

テストは偽の Chat API（tests/fakes.py）で行い、ネットワークにはつなぎません。

ライセンス

MIT