______________________________________________________________________

谷歌聊天Webhook MCP服务器

![CI](https://github.com/ice3x2/google-chat-webhook-mcp/actions) ](https://www.npmjs.com/package/google-chat-webhook-mcp) ![License: MIT](https://opensource.org/licenses/MIT)

一个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（推荐）

npm install -g google-chat-webhook-mcp

来源（发展）

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安装

{
  "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"
      }
    }
  }
}

源安装

{
  "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 在项目根目录中：

{
  "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：

# 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代码）

通过以下方式支持MCP 代理模式在工作区或用户设置中配置MCP服务器。

配置文件位置

选择以下选项之一：

用户设置: ~/.vscode/settings.json 或 %APPDATA%\Code\User\settings.json （Windows）
工作区设置: .vscode/settings.json 在项目根目录中
Claude代码配置 （自动导入）：复制自 ~/.claude.json

配置（mcp.json格式）

添加到 settings.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代码中打开GitHub Copilot聊天
启用代理模式（如果尚未启用）
开始对话-副驾驶将自动访问MCP工具
工具在执行前需要批准

例子：

@workspace Send a deployment summary to Google Chat

📝 备注GitHub Copilot的MCP支持包括代理模式，允许复杂的工作流程。确保您使用的是最新的VS Code和GitHub Copilot扩展。

3.其他MCP客户端

适用于任何兼容MCP的客户端：

{
  "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

参数：

{
  "text": "Hello, Google Chat!"
}

2. `send_google_chat_cards_v2`

直接发送V2格式的卡片（高级用户）

参数：

{
  "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

参数：

{
  "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\	--\	--\	`	单空间桌
图像	`![alt](https://...)`	图像小部件（验证后）
链接	`[text](https://...)`	可点击链接
水平线	`---` 或 `***`	分流器
块引用	`> quote`	缩进+灰色文本

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:

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)

{
  "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 在项目根目录中：

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/*

调试：

cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"

Q：卡V2转换失败

A.：使用 fallbackToText 选项：

{
  "markdown": "...",
  "fallbackToText": true
}

查看日志以了解详细信息：

cat logs/errors-YYYY-MM-DD.log

Q：日志文件太多

A.：根据环境变量进行调整：

{
  "env": {
    "LOG_LEVEL": "WARN",
    "LOG_RETENTION_DAYS": "7"
  }
}

Q：多个谷歌聊天空间

A.：注册单独的MCP服务器实例：

{
  "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许可证- 许可证

链接

______________________________________________________________________

韩国人：

![CI](https://github.com/ice3x2/google-chat-webhook-mcp/actions) ](https://www.npmjs.com/package/google-chat-webhook-mcp) ![License: MIT](https://opensource.org/licenses/MIT)

通过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安装（建议）

npm install -g google-chat-webhook-mcp

安装源（用于开发）

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：

打开Google Chat空间
顶部菜单→“应用程序和集成”→“Webhook管理”
单击“添加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时

{
  "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"
      }
    }
  }
}

安装源时

{
  "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 创建文件：

{
  "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：

# 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）：

~/.claude.json 编辑（Windows %USERPROFILE%\.claude.json)
保存文件
Claude Code正在运行时重新启动

设置项目级别 （.mcp.json）：

在项目根目录中 .mcp.json 创建
将敏感数据设置为环境变量
.mcp.json向版本控制系统提交
使用“Send a message to Google Chat”等命令

2.GitHub副本（VS代码）

银 代理模式通过支持MCP。可以在工作空间或用户设置中配置MCP服务器。

设置文件位置

选择以下选项之一：

用户设置: ~/.vscode/settings.json 或者 %APPDATA%\Code\User\settings.json （Windows）
工作空间设置：项目根目录的 .vscode/settings.json
Claude Code设置 （自动导入）： ~/.claude.json从复制

如何设置（mcp.json格式）

settings.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协议的客户端：

{
  "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格式传输（面向高级用户）

**参数：**

{ "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\|--\|--\|` |固定宽度字体表|
| **图像** | `![alt](https://...)` |图像构件（验证URL后）|
| **链接** | `[텍스트](https://...)` |可点击的链接|
| **水平线** | `---` 或者 `***` |分隔线|
| **引文** | `> quote` |缩进+灰色文本|

**示例Markdown：**

프로젝트 배포 완료 🚀

주요 변경사항

성능 개선: API 응답 속도 30% 향상
버그 수정: 로그인 오류 해결
새 기능 추가

배포 상태

환경	상태	버전
Production	✅	v2.1.0
Staging	✅	v2.1.0

다음 단계

모니터링 24시간
사용자 피드백 수집
다음 스프린트 계획

코드 예제:

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` 创建文件：

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）：**

$env:GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"


**Linux/macOS（Bash/Zsh）：**

export GOOGLE_CHAT_WEBHOOK_URL="https://chat.googleapis.com/v1/spaces/xxx/messages?key=xxx&token=xxx"


## 开发

의존성 설치

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）

{ "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/*`必须为

**调试：**

로그 확인

cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"


**验证失败时的行为：**

- 图像由文本链接替换
- 示例： `⚠️ 이미지 로드 실패: https://... (HTTP 404: Not Found)`

### 问：Cards V2转换失败

**A.**：请确认：

1. **使用fallback ToText选项**:

{ "markdown": "...", "fallbackToText": true }


   转换失败时会自动发送到文本。

1. **检查日志中的原因**:

cat logs/errors-YYYY-MM-DD.log


1. **不支持的Markdown语法**:

   - 脚注（footnotes）
   - 定义列表（Definition lists）
   - 复杂的HTML标签

### 问：日志文件堆积太多

**A.**：调整为环境变量：

{ "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：

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服务器实例：

{ "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）

工作流： 

## 贡献

欢迎话题和PR！

## 许可证

MIT许可证- [许可证](LICENSE)

## 文件

- [记录设计](docs/logging-design.md)
- [CI设置指南](docs/ci-setup.md)
- [Markdown实施计划](docs/markdown-to-cards-implementation.md)

## 相关项目

- [模型上下文协议](https://github.com/modelcontextprotocol)
- [克劳德代码](https://claude.ai/desktop)
- [谷歌聊天API](https://developers.google.com/chat)

Google Chat Webhook MCP Server

快速接入

详细介绍

谷歌聊天Webhook MCP服务器

特性

安装

npm（推荐）

来源（发展）

谷歌聊天Webhook设置

MCP客户端配置

1.克劳德密码

配置文件位置

npm安装

源安装

配置范围

项目范围配置（.mcp.json）

如何申请

2.GitHub副本（VS代码）

配置文件位置

配置（mcp.json格式）

特性

与代理模式一起使用

3.其他MCP客户端

用法

MCP工具（3个工具）

1. send_google_chat_text

2. send_google_chat_cards_v2

3. send_google_chat_markdown ⭐ 推荐

Claude代码使用示例

支持的Markdown语法

Environment Variables

Required

Optional (Logging)

Configuration Methods

Claude Code (~/.claude.json)

.env文件（开发）

局限性

Google Chat API限制

Markdown转换限制

常见问题解答

Q： 图像未显示

Q： 卡V2转换失败

Q： 日志文件太多

Q： 多个谷歌聊天空间

许可证

链接

主要功能

安装

npm安装（建议）

安装源（用于开发）

创建Google Chat Webhook URL

MCP客户端设置

1.克劳德密码

设置文件位置

安装npm时

安装源时

设置镜

设置项目级别（.mcp.json）

应用方法

2.GitHub副本（VS代码）

设置文件位置

如何设置（mcp.json格式）

功能

在代理模式下使用

3.其他MCP客户端

Project Update

프로젝트 배포 완료 🚀

주요 변경사항

배포 상태

다음 단계

의존성 설치

빌드

개발 모드 (TypeScript 직접 실행)

Lint 검사

Lint 자동 수정

테스트

로그 확인

目录标签

接入字段

权限和风险

1. `send_google_chat_text`

2. `send_google_chat_cards_v2`

3. `send_google_chat_markdown` ⭐ 推荐

Q：图像未显示

Q：卡V2转换失败

Q：日志文件太多

Q：多个谷歌聊天空间