google-chat-mcp-server

简介

本项目使用 FastMCP，以 Python 编写，为 MCP（Model Control Protocol）服务提供 Google Chat 集成。你可以通过 MCP 工具访问并与 Google Chat 空间及消息交互。

结构

本项目由两个主要组件构成：

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 数据。（你的空间和消息）

功能

• 使用 OAuth2 对 Google Chat API 进行身份验证
• 列出可用的 Google Chat 空间
• 按日期筛选并检索特定空间中的消息
• 以 Markdown 格式呈现卡片消息（机器人、Webhook、CI 通知）
• 本地身份验证服务，方便设置

要求

• 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 Project（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 Client 后，将客户端密钥下载为 .json 文件。将其保存为项目顶层目录下的 credentials.json。

身份验证

有两种可用的身份验证模式：

选项 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 为空。 此类消息会额外包含一个 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）。