使用说明

谷歌聊天MCP服务器

一个模型上下文协议（MCP）服务器，提供全面的谷歌聊天API集成。此服务器实现 MCP规范通过流式HTTP传输，使人工智能助手和代理能够通过标准化的界面与谷歌聊天空间、消息和成员进行交互。

🚀 特性

📧 消息管理（5个工具）

send_message：向空间发送文字或富卡信息
list_消息：在带有筛选选项的空间中列出邮件
get_message：按ID检索特定邮件详细信息
update_message：编辑现有邮件
删除消息：从空间中删除邮件

🏠 空间管理（5个工具）

list_space：列出可访问的聊天空间并进行筛选
get_space：获取特定空间的详细信息
create_space：创建新的群聊空间
update_space：修改空间设置和属性
delete_space：删除空格（仅限管理员）

👥 会员管理（6个工具）

list_members：列出空间中的成员
get_member：获取详细的会员信息
创建会员资格：将用户添加到空间
update_会员资格：更改成员角色和权限
删除会员资格：从空间中删除成员
find_direct_message：与用户一起查找或创建DM空间

🔍 搜索功能（4个工具）

搜索消息：使用查询筛选器跨空间搜索邮件
搜索空间：按名称或描述查找空间
search_members：跨空间搜索成员
get_recent_activity：获取无障碍空间的最新活动

🔗 Webhook集成（5个工具）

send_webhook_message：通过传入的webhooks发送消息
create_card_message：创建丰富的交互式卡片消息
解析 Webhook 事件：分析传入的webhook事件
验证_webhook_签名：验证webhook安全签名
创建交互式卡：创建带有按钮和动作的卡片

📋 先决条件

1.谷歌云项目设置

创建或选择Google Cloud项目

启用Google Chat API：

gcloud services enable chat.googleapis.com

2.创建服务帐户

创建服务帐户：

gcloud iam service-accounts create google-chat-mcp-server \
  --description="Service account for Google Chat MCP Server" \
  --display-name="Google Chat MCP Server"

下载服务帐户密钥：

gcloud iam service-accounts keys create google-chat-mcp-server-key.json \
  --iam-account=google-chat-mcp-server@YOUR_PROJECT_ID.iam.gserviceaccount.com

3.谷歌聊天应用程序配置

首选谷歌云控制台>API和服务>凭据
创建新的“谷歌聊天应用”凭据
使用以下配置聊天应用程序：
- 应用程序名称：谷歌聊天MCP服务器
- 头像URL：（可选）
- 描述：用于Google聊天集成的MCP服务器
- 功能：可以添加到空间和组对话中
- 连接设置HTTP 终端（如果需要，用于 Webhooks）
- 能见度：适用于您域中的特定人员/组

4.所需的OAuth范围

服务帐户需要以下OAuth 2.0作用域：

https://www.googleapis.com/auth/chat.bot
https://www.googleapis.com/auth/chat.spaces
https://www.googleapis.com/auth/chat.messages
https://www.googleapis.com/auth/chat.memberships

🛠️ 安装

1.克隆和设置

git clone https://github.com/pueteam/google-chat-mcp-server.git
cd google-chat-mcp-server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

2.环境配置

复制示例环境文件并配置：

cp .env.example .env

编辑 .env 使用您的设置：

# Required: Path to service account JSON file
GOOGLE_APPLICATION_CREDENTIALS=/path/to/google-chat-mcp-server-key.json

# Optional: Default space for operations (can be overridden per tool call)
GOOGLE_CHAT_DEFAULT_SPACE=spaces/AAAA1234567

# Optional: Logging level
LOG_LEVEL=INFO

3.验证设置

测试身份验证和基本功能：

source venv/bin/activate
python -c "
from src.google_chat_mcp.auth.google_auth import GoogleChatAuth
import asyncio

async def test():
    auth = GoogleChatAuth('google-chat-mcp-server-key.json')
    await auth.initialize()
    print('✅ Authentication successful')

asyncio.run(test())
"

🚀 运行服务器

MCP流式HTTP服务器（推荐）

服务器支持SSE流和JSON响应模式：

# Start with SSE streaming (default)
python stateless_streamable_server.py --port 8004 --response sse

# Start with JSON responses
python stateless_streamable_server.py --port 8004 --response json

# With custom log level
python stateless_streamable_server.py --port 8004 --log-level DEBUG --response sse

服务器选项：

--port, -p：要监听的端口（默认值：8004）
--log-level, -l：日志记录级别（调试、信息、警告、错误）
--response, -r：响应类型（sse、json）

MCP端点

服务器将在以下位置可用：

端点: http://localhost:8004/mcp
协议：MCP流式HTTP
运输：HTTP与JSON-RPC 2.0

🔧 MCP客户端集成

配置

要将此服务器与MCP客户端一起使用，请添加以下配置：

{
  "name": "google_chat_mcp_server",
  "endpoint": "http://localhost:8004/mcp",
  "transport_type": "http",
  "enabled": true,
  "auth_type": "none",
  "description": "Google Chat API integration with 25 tools for messaging, spaces, members, search, and webhooks"
}

连接详细信息

使用以下方式连接到服务器：

统一资源定位符: http://localhost:8004/mcp
协议：MCP流式HTTP
标头:
- Accept: application/json, text/event-stream
- Content-Type: application/json

可用的JSON-RPC方法

initialize：初始化MCP会话
tools/list：列出所有25个可用工具
tools/call：执行特定工具
ping：健康检查

📚 工具使用示例

发送信息

{
  "jsonrpc": "2.0",
  "id": "msg1",
  "method": "tools/call",
  "params": {
    "name": "send_message",
    "arguments": {
      "space": "spaces/AAAA1234567",
      "text": "Hello from MCP!"
    }
  }
}

创建富卡

{
  "jsonrpc": "2.0",
  "id": "card1",
  "method": "tools/call",
  "params": {
    "name": "create_card_message",
    "arguments": {
      "title": "Status Update",
      "subtitle": "System Health Check",
      "text": "All systems operational",
      "color": "#00FF00",
      "buttons": [
        {
          "text": "View Details",
          "url": "https://dashboard.example.com"
        }
      ]
    }
  }
}

搜索邮件

{
  "jsonrpc": "2.0",
  "id": "search1",
  "method": "tools/call",
  "params": {
    "name": "search_messages",
    "arguments": {
      "query": "project status",
      "limit": 10,
      "order_by": "create_time desc"
    }
  }
}

🏗️ 建筑

项目结构

google-chat-mcp-server/
├── src/
│   └── google_chat_mcp/
│       ├── auth/
│       │   └── google_auth.py      # Google API authentication
│       ├── tools/
│       │   ├── __init__.py         # Tool exports
│       │   ├── base.py             # Base tool class
│       │   ├── messages.py         # Message management tools
│       │   ├── spaces.py           # Space management tools
│       │   ├── members.py          # Member management tools
│       │   ├── search.py           # Search tools
│       │   └── webhooks.py         # Webhook tools
│       └── server.py               # Legacy STDIO server
├── stateless_streamable_server.py  # MCP Streamable HTTP server
├── requirements.txt                # Python dependencies
├── .env.example                    # Environment configuration template
├── Dockerfile                      # Container image definition
└── README.md                       # This file

MCP合规性

此服务器完全符合MCP规范：

✅ 协议版本: 2024-11-05
✅ 运输具有SSE和JSON模式的可串流HTTP
✅ JSON-RPC 2.0：正确的请求/响应格式
✅ 错误处理：标准JSON-RPC错误代码
✅ 工具架构：OpenAPI兼容工具定义
✅ 内容类型：结构化文本内容响应

🔍 故障排除

常见问题

身份验证错误

Error: Could not load the default credentials

验证 GOOGLE_APPLICATION_CREDENTIALS 路径正确
确保服务帐户密钥文件存在并且可读
检查服务帐户是否需要OAuth作用域

API权限错误

Error: The caller does not have permission to access the Chat API

验证Google Chat API是否已在您的项目中启用
确保聊天应用程序配置正确
检查服务帐户是否已添加到相关空间

连接问题

Error: Connection refused to localhost:8004

验证服务器是否正在运行： ps aux | grep stateless_streamable_server
检查端口可用性： lsof -i :8004
查看服务器日志以查找启动错误

工具执行错误

Error: Invalid space name

确保空间名称使用以下格式： spaces/AAAA1234567
验证机器人是否可以访问目标空间
检查空间是否存在且是否可访问

调试模式

运行调试日志以进行详细的故障排除：

python stateless_streamable_server.py --port 8004 --log-level DEBUG

健康检查

验证服务器运行状况：

curl -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -X POST http://localhost:8004/mcp \
     -d '{"jsonrpc":"2.0","id":"health","method":"ping","params":{}}'

📊 监控和日志

服务器日志

监控服务器活动：

# Follow real-time logs
tail -f google_chat_mcp_*.log

# Search for errors
grep -i error google_chat_mcp_*.log

# View recent startup
head -20 google_chat_mcp_*.log

性能指标

可用工具：5个类别共25个
响应时间：API调用通常＜500ms
并发连接：支持多个MCP客户端
内存使用：~60-80MB基线

🤝 与AI助手集成

此MCP服务器遵循开放的MCP标准，使其与任何符合MCP的客户端或AI助手框架兼容。

关键集成功能

标准MCP协议：适用于任何符合MCP的客户端
工具发现：通过自动工具发现 tools/list 方法
错误处理：使用标准JSON-RPC错误代码进行优雅的错误处理
架构验证：用于可靠集成的OpenAPI兼容工具模式

快速开始

如上所示启动MCP服务器
配置您的MCP客户端以连接到 http://localhost:8004/mcp
客户端将自动发现所有25个可用工具
开始在您的人工智能工作流程中使用谷歌聊天工具

🔒 安全考虑

服务帐户密钥：安全存储，从不承诺版本控制
网钩签名：使用webhook工具时始终验证webhook签名
网络接入：考虑在本地主机或安全的内部网络上运行
空间权限：Bot只能访问已添加到的空间
速率限制：Google Chat API有费率限制；服务器处理回退

🚀 Docker支持

使用Docker运行服务器：

# Build the image
docker build -t google-chat-mcp-server .

# Run the container
docker run -p 8004:8004 \
  -e GOOGLE_APPLICATION_CREDENTIALS=/app/credentials/google-chat-mcp-server-key.json \
  -v $(pwd)/credentials:/app/credentials \
  google-chat-mcp-server

📈 路线图

[ ] 事件流：通过webhooks实时聊天事件
[ ] 批量操作：批量消息和成员操作
[ ] 高级过滤：更复杂的搜索和过滤选项
[ ] 分析：消息和空间使用分析
[ ] 缓存：对频繁访问的数据进行智能缓存
[ ] CLI工具：用于直接调用工具的命令行界面
[ ] Web用户界面：用于测试和调试的简单web界面

🤝 贡献

欢迎投稿！请随时提交拉取请求或开放问题，以查找错误、功能请求或改进。

开发设置

# Clone the repository
git clone https://github.com/yourusername/google-chat-mcp-server.git
cd google-chat-mcp-server

# Setup development environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install pytest pytest-asyncio black ruff mypy  # Dev dependencies

# Run tests
pytest tests/

# Format and lint
black src/ tests/
ruff src/ tests/
mypy src/

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🤖 使用模型上下文协议构建 此服务器实现了开放 MCP标准用于AI应用集成。