谷歌聊天Webhook MCP服务器
一个MCP(模型上下文协议)服务器,通过webhooks向谷歌聊天发送消息。通过图像验证、结构化日志记录和回退处理,自动将Markdown转换为Google Chat Cards V2格式。
特性
- 🚀 MCP协议支持:与Claude Code、GitHub Copilot和其他MCP客户端集成
- MCP协议支持:与Claude Code、GitHub Copilot和其他MCP客户端集成
- 📝 标记语言→ 卡片V2自动转换:支持标头、列表、代码块、表、图像等
- 🖼️ 图像URL验证:使用HEAD请求进行验证(HTTP状态、内容类型、大小)
- 🔄 自动回退:当Cards V2失败时,自动回退到文本
- 📊 结构化日志记录:JSON格式,保留30天
- ✅ 测试自动化:快照测试、集成测试、CI/CD管道
安装
npm(推荐)```bash
npm install -g google-chat-webhook-mcp
### 来源(发展)```bash
git clone https://github.com/ice3x2/google-chat-webhook-mcp.git
cd google-chat-webhook-mcp
npm install
npm run build
谷歌聊天Webhook设置
在配置MCP服务器之前,请创建一个Google Chat Webhook URL:
- 打开您的谷歌聊天空间
- Menu → “应用程序和集成”→ “管理webhooks”
- 点击“添加webhook”
- 输入名称,然后 复制URL
- 在下面的配置中使用它
MCP客户端配置
1.克劳德密码
配置文件位置
- 视窗:
%USERPROFILE%\.claude.json - macOS/Linux:
~/.claude.json
备注:Claude Desktop使用不同的路径:
- 窗户:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
npm安装```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
#### 源安装```json
{
"mcpServers": {
"google-chat": {
"command": "node",
"args": ["C:\\path\\to\\google-chat-webhook-mcp\\dist\\index.js"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
⚠️ 备注:使用 \\ 或 / 对于Windows路径(例如。, C:/path/to/...)
配置范围
Claude Code支持三种配置范围:
- 用户范围 (全球):
~/.claude.json-适用于所有项目 - 项目范围 (共享):
.mcp.json在项目根目录中-版本受控,团队共享 - 本地范围 (私人):项目特定的个人设置
优先级:本地>项目>用户
项目范围配置(.mcp.json)
对于团队共享的MCP服务器,创建 .mcp.json 在项目根目录中:```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "${GOOGLE_CHAT_WEBHOOK_URL}"
}
}
}
}
**益处**:
- ✅ 版本由Git控制
- ✅ 团队共享配置
- ✅ 环境变量支持: `${VAR}` 或 `${VAR:-default}`
- ✅ 特定于项目的MCP服务器
**环境变量**:每个团队成员都可以设置自己的webhook URL:```bash
# Linux/macOS
export GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
# Windows (PowerShell)
$env:GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
如何申请
用户范围配置 (~/.Claude.JSON):
- 编辑
~/.claude.json(或%USERPROFILE%\.claude.json在Windows上) - 保存文件
- 如果已经运行,请重新启动Claude代码
项目范围配置 (.mcp.json):
- 创建
.mcp.json在项目根中 - 为敏感数据设置环境变量
- 提交
.mcp.json到版本控制 - 使用“向谷歌聊天室发送消息”等命令
2.GitHub副本(VS代码)
VS代码GitHub副本 通过以下方式支持MCP 代理模式在工作区或用户设置中配置MCP服务器。
配置文件位置
选择以下选项之一:
- 用户设置:
~/.vscode/settings.json或%APPDATA%\Code\User\settings.json(Windows) - 工作区设置:
.vscode/settings.json在项目根目录中 - Claude代码配置 (自动导入):复制自
~/.claude.json
配置(mcp.json格式)
添加到 settings.json:```json
{
"github.copilot.chat.mcp.servers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
#### 特性
- **代理模式集成**:代理工作流中提供MCP工具
- **每次会话工具选择**:选择每个会话启用哪些工具
- **STDIO和SSE支持**:支持两种运输类型
- **调试**:内置重启命令和输出日志
#### 与代理模式一起使用
1. 在VS代码中打开GitHub Copilot聊天
1. 启用代理模式(如果尚未启用)
1. 开始对话-副驾驶将自动访问MCP工具
1. 工具在执行前需要批准
**例子:**```
@workspace Send a deployment summary to Google Chat
📝 备注GitHub Copilot的MCP支持包括代理模式,允许复杂的工作流程。确保您使用的是最新的VS Code和GitHub Copilot扩展。
3.其他MCP客户端
适用于任何兼容MCP的客户端:```json
{
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "your-webhook-url"
}
}
## 用法
### MCP工具(3个工具)
Claude Code或其他MCP客户端中的可用工具:
#### 1. `send_google_chat_text`
发送简单的短信
**示例(克劳德代码):**```
Send "Hello from Claude!" to Google Chat
参数:```json
{
"text": "Hello, Google Chat!"
}
#### 2. `send_google_chat_cards_v2`
直接发送V2格式的卡片(高级用户)
**参数:**```json
{
"text": "Card Message",
"cardsV2": [
{
"cardId": "unique-card",
"card": {
"header": { "title": "Card Title" },
"sections": [
{
"widgets": [
{ "textParagraph": { "text": "Card content" } }
]
}
]
}
}
]
}
3. send_google_chat_markdown ⭐ 推荐
将Markdown转换为Cards V2并发送
示例(克劳德代码):```
Send this markdown to Google Chat:
Project Update
- Task 1: ✅ Completed
- Task 2: 🚧 In Progress
Deadline: Tomorrow
**参数:**````json
{
"markdown": "# Title\n\n**Bold** and *italic*\n\n- List item 1\n- List item 2\n\n```python\nprint('Hello')\n```",
"cardTitle": "Markdown Message",
"fallbackToText": true
}
````
**选项:**
- `cardTitle`:卡片顶部显示的标题(可选)
- `fallbackToText`:转换失败时自动以文本形式发送(默认值:false)
### Claude代码使用示例
设置后,Claude将在您自然聊天时自动使用MCP工具:
**👤 用户:**
> “向Google聊天室发送项目状态更新。以标记列表的形式显示3个已完成的任务和2个正在进行的任务。”
**🤖 克劳德:**
> (自动呼叫 `send_google_chat_markdown` 工具)
>
> 我已将消息发送到谷歌聊天室。项目状态已更新。
### 支持的Markdown语法
用Claude或MCP客户端编写的Markdown会自动转换为Google Chat Cards V2。
语法 · Markdown示例 · 谷歌聊天渲染
**标头** · `# H1`, `## H2`, `### H3` · 大胆,尺寸不同
**加粗** · `**bold**` 或 `__bold__` · **粗体**
**斜体** · `*italic*` 或 `_italic_` · *斜体*
**内联代码** · `` `code` `` · `code` (单空间)
**代码块**```` ```python\ncode\n``` ```` · 语法突出显示框
**有序列表** · `1. First\n2. Second` 1.第一
2.第二|
**列表** · `- Item` 或 `* Item` · •项目
**嵌套的列表** · ` - nested` (2空格缩进) · •嵌套(Em空格)
**表格** · `\ · A \ · B \ · \n\ · --\ · --\ · ` · 单空间桌
**图像** · `` · 图像小部件(验证后)
**链接** · `text` · 可点击链接
**水平线** · `---` 或 `***` · 分流器
**块引用** · `> quote` · 缩进+灰色文本
**Markdown示例:**````markdown
# Project Deployment Complete 🚀
## Key Changes
- **Performance**: API response 30% faster
- **Bug Fix**: Login error resolved
- New feature added
## Deployment Status
| Environment | Status | Version |
|-------------|--------|---------|
| Production | ✅ | v2.1.0 |
| Staging | ✅ | v2.1.0 |
## Next Steps
1. Monitor for 24 hours
2. Collect user feedback
3. Plan next sprint
Code example:
```python
def deploy():
print("Deploying v2.1.0...")
return True````
看 [文档](https://docs.example.com) 了解详情。
````
**Result:** Headers, lists, tables, and code blocks are all visually distinguished in Google Chat.
## Environment Variables
### Required
| Variable | Description | Example |
|----------|-------------|---------|
| `GOOGLE_CHAT_WEBHOOK_URL` | Google Chat Webhook URL | `https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx` |
### Optional (Logging)
| Variable | Description | Default | Values |
|----------|-------------|---------|--------|
| `LOG_LEVEL` | Log level | `INFO` | `DEBUG`, `INFO`, `WARN`, `ERROR` |
| `LOG_DIR` | Log directory path | `./logs` | Absolute/relative path |
| `LOG_RETENTION_DAYS` | Days to keep logs | `30` | Number (days) |
| `LOG_ENABLE_CONSOLE` | Enable console output | `true` | `true`, `false` |
### Configuration Methods
#### Claude Code (~/.claude.json)```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx",
"LOG_LEVEL": "INFO",
"LOG_RETENTION_DAYS": "30"
}
}
}
}
````
#### .env文件(开发)
创建 `.env` 在项目根目录中:```env
GOOGLE_CHAT_WEBHOOK_URL=https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx
LOG_LEVEL=INFO
LOG_DIR=./logs
LOG_RETENTION_DAYS=30
LOG_ENABLE_CONSOLE=true
局限性
Google Chat API限制
| 项目 | 限制 | 解决方法 |
|---|---|---|
| 图像协议 | 仅HTTPS | HTTP URL已替换为文本链接 |
| 图像尺寸 | 最大5MB | 验证失败时显示为链接 |
| 图像认证 | 仅限公共URL | 如果需要身份验证,则无法访问 |
| 内容类型 | image/* 仅 |
HTML页面被拒绝 |
| Markdown支持 | 有限 | 近似不支持的语法 |
Markdown转换限制
✅ 完全支持:
- 集管(H1~H6)
- 粗体、斜体、内联代码
- 有序/无序列表(最多3级)
- 代码块(语法高亮显示)
- 表格(单空间)
- 链接、图片
⚠️ 部分支持:
- 复杂的嵌套→ 简体
- HTML标记→ 转换为文本
- 引用块→ 显示为凹痕
❌ 不支持:
- 脚注
- 定义列表
- 数学公式(LaTeX)
- 任务复选框(
- [ ],- [x]) - 表情符号快捷方式(
:smile:,Unicode表情符号工作)
常见问题解答
Q: 图像未显示
A.:图像验证失败的原因:
- 仅限HTTPS (不支持HTTP)
- 文件大小:必须低于5MB
- 公共访问:必须无需身份验证即可访问
- 内容类型:响应标头必须为
image/*
调试:```bash
cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"
### Q: 卡V2转换失败
**A.**:使用 `fallbackToText` 选项:```json
{
"markdown": "...",
"fallbackToText": true
}
查看日志以了解详细信息:```bash
cat logs/errors-YYYY-MM-DD.log
### Q: 日志文件太多
**A.**:根据环境变量进行调整:```json
{
"env": {
"LOG_LEVEL": "WARN",
"LOG_RETENTION_DAYS": "7"
}
}
Q: 多个谷歌聊天空间
A.:注册单独的MCP服务器实例:```json
{
"mcpServers": {
"google-chat-team-a": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-a/..."
}
},
"google-chat-team-b": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-b/..."
}
}
}
}
## 许可证
MIT许可证- 许可证
## 链接
- 模型上下文协议
- 克劳德代码
- 谷歌聊天API
______________________________________________________________________
韩国人:
通过Google Chat网络钩子向模型上下文协议(MCP)服务器发送消息。自动将Markdown转换为Google Chat Cards V2格式,支持图像验证、自动记录和回退处理。
## 主要功能
- 🚀 **MCP协议支持**:与Claude Code、GitHub Copilot等集成
- 📝 **Markdown→Cards V2自动转换**:支持标题、列表、代码块、表格、图像等
- 🖼️ **验证图像URL**:通过HEAD请求验证有效性(HTTP状态、Content-Type、大小)
- 🔄 **自动回退**:Cards V2失败时自动切换为文本
- 📊 **结构化日志记录**:JSON格式,30天自动存档
- ✅ **自动化测试**:快照测试、集成测试、CI/CD管道
## 安装
### npm安装(建议)```bash
npm install -g google-chat-webhook-mcp
安装源(用于开发)```bash
git clone https://github.com/ice3x2/google-chat-webhook-mcp.git
cd google-chat-webhook-mcp
npm install
npm run build
## 创建Google Chat Webhook URL
在设置MCP服务器之前,必须先创建Google Chat Webhook URL:
1. 打开Google Chat空间
1. 顶部菜单→“应用程序和集成”→“Webhook管理”
1. 单击“添加Webhook”
1. 输入名称后 **复制URL**
1. 在以下设置中使用
## MCP客户端设置
### 1.克劳德密码
#### 设置文件位置
- **视窗**: `%USERPROFILE%\.claude.json`
- **macOS/Linux**: `~/.claude.json`
**参考**:Claude Desktop使用不同的路径:
- 窗户: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
#### 安装npm时```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
安装源时```json
{
"mcpServers": {
"google-chat": {
"command": "node",
"args": ["C:\path\to\google-chat-webhook-mcp\dist\index.js"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
**注意**:Windows路径为 `\\` 或者 `/` 使用(例如: `C:/path/to/...`)
#### 设置镜
Claude Code支持三种设置标记:
1. **用户范围** (全局): `~/.claude.json` -适用于所有项目
1. **项目范围** (共享):项目根目录的 `.mcp.json` -版本控制,团队共享
1. **本地范围** (个人):特定于项目的个人设置
**优先级**:本地>项目>用户
#### 设置项目级别(.mcp.json)
要与团队共享的MCP服务器设置在项目根目录中 `.mcp.json` 创建文件:```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "${GOOGLE_CHAT_WEBHOOK_URL}"
}
}
}
}
优点:
- 可以通过Git进行版本管理
- 与团队共享设置
- 支持环境变量:
${VAR}或者${VAR:-기본값} - 设置项目特定的MCP服务器
设置环境变量:每个团队成员都可以设置自己的Webhook URL:```bash
Linux/macOS
export GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
Windows (PowerShell)
$env:GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
#### 应用方法
**设置User级别** (~/.Claude.JSON):
1. `~/.claude.json` 编辑(Windows `%USERPROFILE%\.claude.json`)
1. 保存文件
1. Claude Code正在运行时重新启动
**设置项目级别** (.mcp.json):
1. 在项目根目录中 `.mcp.json` 创建
1. 将敏感数据设置为环境变量
1. `.mcp.json`向版本控制系统提交
1. 使用“Send a message to Google Chat”等命令
### 2.GitHub副本(VS代码)
VS代码GitHub副本银 **代理模式**通过支持MCP。可以在工作空间或用户设置中配置MCP服务器。
#### 设置文件位置
选择以下选项之一:
- **用户设置**: `~/.vscode/settings.json` 或者 `%APPDATA%\Code\User\settings.json` (Windows)
- **工作空间设置**:项目根目录的 `.vscode/settings.json`
- **Claude Code设置** (自动导入): `~/.claude.json`从复制
#### 如何设置(mcp.json格式)
`settings.json`添加到:```json
{
"github.copilot.chat.mcp.servers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"
}
}
}
}
功能
- 代理模式集成:在代理工作流中启用MCP工具
- 选择特定于会话的工具:可以为每个会话选择要激活的工具
- STDIO&SSE支持:支持两种传输方式
- 调试:内置重新启动命令和输出记录
在代理模式下使用
- 在VS Code中打开GitHub Copilot聊天
- 启用代理模式(有时默认启用)
- 开始对话-Copilot自动访问MCP工具
- 工具运行前需要批准
示例:```
@workspace 배포 요약을 Google Chat에 전송해줘
**📝 参考**:GitHub Copilot的MCP支持支持复杂的工作流,包括代理模式。使用最新版本的VS Code和GitHub Copilot扩展。
### 3.其他MCP客户端
适用于所有支持MCP协议的客户端:```json
{
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "your-webhook-url"
}
}
1. Google Chat 스페이스 열기
2. 상단 메뉴 → "앱 및 통합" → "Webhook 관리"
3. "Webhook 추가" 클릭
4. 이름 입력 후 URL 복사
5. 환경 변수에 설정
## 사용법
### MCP 도구 (3가지)
Claude Code이나 다른 MCP 클라이언트에서 다음 도구들을 사용할 수 있습니다:
#### 1. `send_google_chat_text`
간단한 텍스트 메시지 전송
**예시 (Claude Code):**
发送“克劳德你好!”到谷歌聊天````
파라미터:
{
"text": "안녕하세요, Google Chat!"
}````
#### 2. `send_google_chat_cards_v2`
直接以Cards V2格式传输(面向高级用户)
**参数:**
```json
{
"text": "Card Message",
"cardsV2": [
{
"cardId": "unique-card",
"card": {
"header": { "title": "Card Title" },
"sections": [
{
"widgets": [
{ "textParagraph": { "text": "Card content" } }
]
}
]
}
}
]
}```
#### 3. `send_google_chat_markdown` ⭐ **推荐**
自动将Markdown转换为Cards V2并发送
**示例(Claude Code):**
Send this markdown to Google Chat:
Project Update
- Task 1: ✅ Completed
- Task 2: 🚧 In Progress
Deadline: Tomorrow```
参数:
{
"markdown": "# 제목\n\n**굵은 글씨**와 *기울임*\n\n- 리스트 항목 1\n- 리스트 항목 2\n\n```python\nprint('Hello')\n```",
"cardTitle": "마크다운 메시지",
"fallbackToText": true
}````
**可选:**
- `cardTitle`:显示在卡片顶部的标题(可选)
- `fallbackToText`:转换失败时自动发送到文本(默认为false)
### Claude Code使用示例
设置完成后,使用自然语言与Claude对话时,将自动使用MCP工具:
**👤 用户:**
> “请向Google Chat发送项目状态更新,将完成的3个任务和正在进行的2个任务列为标记列表。”
**🤖 克劳德:**
> (自动 `send_google_chat_markdown` 工具调用)
>
> 已向Google Chat发送消息。项目状态已更新。
**👤 用户:**
> “把代码示例也添加到刚刚发送的消息中。”
**🤖 克劳德:**
> (再次通过Markdown创建和发送消息)
### 支持的Markdown语法
在Claude或MCP客户端上使用Markdown创建消息时,它会自动转换为Google Chat Cards V2。
|语法| Markdown示例| Google Chat呈现|
|------|---------------|-------------------|
| **标题** | `# H1`, `## H2`, `### H3` |粗体字+大小差别|
| **粗体** | `**bold**` 或者 `__bold__` | **粗体** |
| **倾斜** | `*italic*` 或者 `_italic_` | *斜体* |
| **内联代码** | `` `code` `` | `code` (固定宽度字体)|
| **代码块** | ```````python\ncode\n``````` |语法突出显示框|
| **顺序列表** | `1. First\n2. Second` 1.第一
2.第二|
| **非顺序列表** | `- Item` 或者 `* Item` |•项目|
| **嵌套列表** | ` - nested` (缩进2格)•nested(Em space)
| **表** | `\| A \| B \|\n\|--\|--\|` |固定宽度字体表|
| **图像** | `` |图像构件(验证URL后)|
| **链接** | `[텍스트](https://...)` |可点击的链接|
| **水平线** | `---` 或者 `***` |分隔线|
| **引文** | `> quote` |缩进+灰色文本|
**示例Markdown:**
````markdown
# 프로젝트 배포 완료 🚀
## 주요 변경사항
- **성능 개선**: API 응답 속도 30% 향상
- **버그 수정**: 로그인 오류 해결
- 새 기능 추가
## 배포 상태
| 환경 | 상태 | 버전 |
|------|------|------|
| Production | ✅ | v2.1.0 |
| Staging | ✅ | v2.1.0 |
## 다음 단계
1. 모니터링 24시간
2. 사용자 피드백 수집
3. 다음 스프린트 계획
코드 예제:```python
def deploy():
print("Deploying v2.1.0...")
return True
有关详细信息,请访问 文件请参阅。````
변환 결과: Google Chat에서 헤더, 리스트, 표, 코드블록이 모두 시각적으로 구분되어 표시됩니다.
환경 변수
필수 환경 변수
| 변수명 | 설명 | 예시 |
|---|---|---|
GOOGLE_CHAT_WEBHOOK_URL |
Google Chat Webhook URL | https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx |
선택 환경 변수 (로깅)
| 변수명 | 설명 | 기본값 | 허용값 |
|---|---|---|---|
LOG_LEVEL |
로그 레벨 | INFO |
DEBUG, INFO, WARN, ERROR |
LOG_DIR |
로그 디렉토리 경로 | ./logs |
절대/상대 경로 |
LOG_RETENTION_DAYS |
로그 보관 일수 | 30 |
숫자 (일) |
LOG_ENABLE_CONSOLE |
콘솔 출력 여부 | true |
true, false |
설정 방법
Claude Code (~/.claude.json)
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx",
"LOG_LEVEL": "INFO",
"LOG_RETENTION_DAYS": "30"
}
}
}
}````
#### .env文件(用于开发)
在项目根目录中 `.env` 创建文件:
```env
GOOGLE_CHAT_WEBHOOK_URL=https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx
LOG_LEVEL=INFO
LOG_DIR=./logs
LOG_RETENTION_DAYS=30
LOG_ENABLE_CONSOLE=true```
#### 系统环境变量
**Windows(PowerShell):**
```powershell
$env:GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"```
**Linux/macOS(Bash/Zsh):**
```bash
export GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"```
## 开发
```bash
# 의존성 설치
npm install
# 빌드
npm run build
# 개발 모드 (TypeScript 직접 실행)
npm run dev
# Lint 검사
npm run lint
# Lint 자동 수정
npm run lint:fix
# 테스트
npm run test:snapshot # 스냅샷 테스트 (12개)
npm run test:logging # 로깅 시스템 테스트
npm run test:integration # 통합 테스트 (웹훅 필요)
npm test # 전체 테스트```
## 体系结构
src/
├── index.ts # 진입점
├── server.ts # MCP 서버 설정
├── tools/ # MCP 도구
│ ├── sendTextMessage.ts # 텍스트 전송
│ ├── sendCardsV2Message.ts # Cards V2 전송
│ ├── sendMarkdownMessage.ts # Markdown 전송 (메인)
│ └── markdownToCards.ts # Markdown → Cards V2 변환
├── utils/ # 유틸리티
│ ├── imageValidator.ts # 이미지 URL 검증
│ ├── cardsV2Validator.ts # Cards V2 스키마 검증
│ ├── logger.ts # 로깅 시스템
│ └── logCleaner.ts # 로그 정리
└── types/ # 타입 정의
├── markdown.ts
├── googleChat.ts
└── log.ts```
记录
日志文件结构
logs/
├── app-2025-10-29.log # 일별 로그 (모든 레벨)
├── errors-2025-10-29.log # 에러 전용 로그
└── ... # 30일 자동 삭제```
### 日志格式(JSON)
```json
{
"timestamp": "2025-10-29T12:34:56.789Z",
"level": "INFO",
"module": "sendMarkdownMessage",
"event": "message_sent",
"messageId": "spaces/xxx/messages/yyy",
"elapsed": 123,
"usedFallback": false,
"cardTitle": "Test Card"
}```
### 日志事件
- `message_sent`:消息发送成功
- `fallback_used`:使用回退(Cards V2→Text)
- `image_validation_failed`:映像验证失败
- `send_failed`:传输失败
- `validation_failed`:验证失败
### 整理日志
- 服务器启动时自动清除(删除30天以上的日志)
- 每24小时自动运行
- 环境变量 `LOG_RETENTION_DAYS`可以设置为
## 限制条件
### Google Chat API限制
|项目|限制|响应方式|
|------|------|-----------|
| **映像协议** |仅支持HTTPS | HTTP URL将替换为文本链接|
| **图像大小** |最大5MB|验证失败时显示为链接|
| **映像认证** |只能公开URL,需要认证时无法访问|
| **内容类型** | `image/*`只允许|拒绝HTML页面等|
| **Markdown支持** |有限的|不支持的语法转换为近似值|
### Markdown转换限制
**完全支持:**
- 标题(H1-H6)
- 粗体、斜体、内嵌代码
- 顺序/非顺序列表(最多嵌套3个步骤)
- 代码块(突出显示语法)
- 表(固定宽度字体)
- 链接,图像
**部分支持:**
- 复杂的嵌套结构→简化
- HTML标签→转换为文本
- 引文→缩进
**不支持:**
- 脚注(footnotes)
- 定义列表(Definition lists)
- 数学公式(LaTeX)
- 任务复选框(`- [ ]`, `- [x]`)
- Emoji快捷代码(`:smile:` 等,可以进行Unicode聚合)
### 性能和限制
- **映像验证超时**:5秒
- **Webhook请求超时**:5秒
- **日志文件大小**:无限制(30天自动删除)
- **并发请求**:无限制(遵守Google Chat API限制)
### 安全注意事项
⚠️ **Webhook URL是敏感信息:**
- 不要提交到Git
- 禁止暴露在公共存储库中
- 建议定期再生
- `.env` 文件 `.gitignore`必须包括在中
## 常见问题解答
### 问:不显示图像
**A.**:图像URL验证失败原因:
1. **仅支持HTTPS** (HTTP不可用)
1. **文件大小**:必须小于5 MB
1. **公开访问**:必须是无需身份验证即可访问的URL
1. **内容类型**:响应头 `image/*`必须为
**调试:**
```bash
# 로그 확인
cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"```
**验证失败时的行为:**
- 图像由文本链接替换
- 示例: `⚠️ 이미지 로드 실패: https://... (HTTP 404: Not Found)`
### 问:Cards V2转换失败
**A.**:请确认:
1. **使用fallback ToText选项**:
```json
{
"markdown": "...",
"fallbackToText": true
}```
转换失败时会自动发送到文本。
1. **检查日志中的原因**:
```bash
cat logs/errors-YYYY-MM-DD.log```
1. **不支持的Markdown语法**:
- 脚注(footnotes)
- 定义列表(Definition lists)
- 复杂的HTML标签
### 问:日志文件堆积太多
**A.**:调整为环境变量:
```json
{
"env": {
"LOG_LEVEL": "WARN",
"LOG_RETENTION_DAYS": "7"
}
}```
- `LOG_LEVEL=ERROR`:仅记录错误
- `LOG_RETENTION_DAYS=7`:仅保留7天
- `LOG_ENABLE_CONSOLE=false`:禁用控制台输出
### 问:运行npx时出现“command not found”错误
**A.**:验证是否安装了Node.js和npm:
```bash
node --version # v18.0.0 이상 권장
npm --version```
如果未安装:
- **视窗**: https://nodejs.org/从下载
- **macOS**: `brew install node`
- **Linux**: `sudo apt install nodejs npm` (Ubuntu/Debian)
### 问:如何安全地管理Webhook URL?
**A.**:
1. **使用环境变量** (不要直接写入配置文件)
1. **不要提交到Git** (检查gitignore)
1. **定期再生** (疑似泄露时)
1. **从Google Chat中删除Webhook**可通过无效
### 问:我想向多个Google Chat空间发送消息
**A.**:为每个空间注册不同的MCP服务器实例:
```json
{
"mcpServers": {
"google-chat-team-a": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-a/..."
}
},
"google-chat-team-b": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "https://chat.googleapis.com/.../team-b/..."
}
}
}
}
可以在Claude中使用“Send to team-a”或“Send to team-b”。
CI/CD
通过GitHub Actions实现自动化:
- Node.js 18.x,20.x矩阵构建
- ESLint,构建,测试
- 测试(12个)快照
- 集成测试(master branch)
工作流: .github/workflows/ci.yml
贡献
欢迎话题和PR!
许可证
MIT许可证- 许可证
文件
- 记录设计
- CI设置指南
- Markdown实施计划
相关项目
- 模型上下文协议
- 克劳德代码
- 谷歌聊天API
```
