google-chat-mcp-server

はじめに

このプロジェクトは、FastMCP を使用して Python で記述された MCP（Model Control Protocol）サーバー向けの Google Chat 連携機能を提供します。MCP ツールを通じて、Google Chat のスペースやメッセージにアクセスし、操作できます。

構成

このプロジェクトは、主に次の 2 つのコンポーネントで構成されています。

1. Google Chat ツールを備えた MCP サーバー：Model Control Protocol を通じて Google Chat を操作するツールを提供します。

   • FastMCP で記述されています
   • server.py：Google Chat ツールを備えた MCP サーバーのメイン実装
   • google_chat.py：Google Chat API との連携および認証処理

2. 認証サーバー：Google アカウント認証用の独立したコンポーネント

   • FastAPI で記述されています
   • Google との OAuth2 フローを処理します
   • アクセストークンを保存および管理します
   • 単独で実行することも、MCP サーバーの一部として実行することもできます
   • server_auth.py：認証サーバーの実装

認証フローでは、Google API トークンを取得して更新できます。取得したトークンは、MCP ツールが Google Chat のデータ（スペースとメッセージ）にアクセスするために使用します。

機能

• Google Chat API との OAuth2 認証
• 利用可能な Google Chat スペースの一覧表示
• 日付による絞り込みに対応した、指定スペースからのメッセージ取得
• カードメッセージ（ボット、Webhook、CI 通知）を Markdown としてレンダリングして読み込み
• セットアップが簡単なローカル認証サーバー

要件

• Python 3.13+
• 次の API を有効にした Google Cloud プロジェクト：
  • Google Chat API
  • People API（ユーザーの表示名用）
• Google Cloud Console で取得した OAuth2 認証情報

使い方

Google OAuth ログインの準備

1. このプロジェクトをクローンします

   git clone https://github.com/chy168/google-chat-mcp-server.git
   cd google-chat-mcp-server
   

2. Google Cloud プロジェクト（GCP）を準備します
3. Google Cloud Console（https://console.cloud.google.com/auth/overview?project=<YOUR_PROJECT_NAME>）を開きます
4. Google Auth Platform > Clients > (+) Create client > Web application 参考：https://developers.google.com/identity/protocols/oauth2/?hl=en Authorized JavaScript origins に http://localhost:8000 を追加します Authorized redirect URIs に http://localhost:8000/auth/callback を追加します
5. OAuth 2.0 クライアントを作成したら、クライアントシークレットを .json ファイルとしてダウンロードします。プロジェクトのトップレベルに credentials.json として保存します。

認証

利用できる認証モードは 2 つあります。

オプション 1：CLI モード（ヘッドレス環境／リモート環境に推奨）

uv run python server.py --auth cli

次の手順を実行します。

1. 認証 URL が表示されます
2. 任意のブラウザーで URL を開きます（別のデバイスでも構いません）
3. Google の認証を完了します
4. ブラウザーからリダイレクト URL をコピーし、ターミナルに貼り付けます
5. トークンが token.json として保存されます

オプション 2：Web モード（ローカルブラウザーが利用できる環境向け）

uv run python server.py --auth web --port 8000

• http://localhost:8000/auth をブラウザーで開きます
• Google ログインを完了します
• トークンが token.json として保存されます

MCP の設定（mcp.json）

{
    "mcpServers": {
        "google_chat": {
            "command": "uv",
            "args": [
                "--directory",
                "<YOUR_REPO_PATH>/google-chat-mcp-server",
                "run",
                "server.py",
                "--token-path",
                "<YOUR_REPO_PATH>/google-chat-mcp-server/token.json"
            ]
        }
    }

Docker / Podman

コンテナーを実行する

# Mount your project directory containing token.json
docker run -it --rm \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --token-path=/data/token.json

# or with podman
podman run -it --rm \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --token-path=/data/token.json

コンテナー内で認証サーバーを実行する

# Web mode
docker run -it --rm \
  -p 8000:8000 \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --auth web --host 0.0.0.0 --port 8000 --token-path=/data/token.json

# CLI mode (for headless environments)
docker run -it --rm \
  -v /path/to/your/project:/data \
  ghcr.io/chy168/google-chat-mcp-server:latest \
  --auth cli --token-path=/data/token.json

ツール

MCP サーバーは次のツールを提供します。

Google Chat ツール

• get_chat_spaces() - ボットがアクセスできるすべての Google Chat スペースを一覧表示します
• get_space_messages(space_name: str, start_date: str, end_date: str = None) - 時刻での絞り込み（任意）に対応し、指定した Google Chat スペースのメッセージを一覧表示します
• search_messages(space_name: str, query: str, start_date: str = None, end_date: str = None) - メッセージ本文およびカードのテキストを、大文字と小文字を区別せずに部分一致検索します

カードメッセージ

ボットや Webhook（CI、監視、アラート）は通常、カードを投稿し、メッセージの text は空のままにします。 このようなメッセージには、カードを Markdown としてレンダリングした cards_text フィールドが追加されます。カードとセクションの見出しは見出しとして、ラベル付きの値はリスト項目として、ボタンとクリック可能なテキストはリンクとして表示されます。

{"sender": "CI", "text": null, "cards_text": "## ❌ my-pipeline #42\n\n_Build failed_\n\n- **Duration** : 11 sec\n[Open build](https://ci.example.com/42)"}

開発とデバッグ

イメージをビルドする

docker build -t google-chat-mcp-server:latest .
# or
podman build -t google-chat-mcp-server:latest .

デバッグ

fastmcp dev server.py --with-editable .

テストを実行する

uv run python -m unittest discover -s tests -t .

同じテストスイートが、プッシュとプルリクエストのたびに GitHub Actions で実行されます（.github/workflows/test.yml）。