---
# Google Chat Webhook MCP Server
[](https://github.com/ice3x2/google-chat-webhook-mcp/actions)
[](https://www.npmjs.com/package/google-chat-webhook-mcp)
[](https://opensource.org/licenses/MIT)
An MCP (Model Context Protocol) server that sends messages to Google Chat via webhooks. Automatically converts Markdown to Google Chat Cards V2 format with image validation, structured logging, and fallback handling.
## Features
- 🚀 **MCP Protocol Support**: Integrates with Claude Code, GitHub Copilot, and other MCP clients
- � **MCP Protocol Support**: Integrates with Claude Code, GitHub Copilot, and other MCP clients
- �📝 **Markdown → Cards V2 Auto-conversion**: Supports headers, lists, code blocks, tables, images, and more
- 🖼️ **Image URL Validation**: Validates with HEAD requests (HTTP status, Content-Type, size)
- 🔄 **Auto Fallback**: Automatically falls back to text when Cards V2 fails
- 📊 **Structured Logging**: JSON format with 30-day retention
- ✅ **Test Automation**: Snapshot tests, integration tests, CI/CD pipeline
## Installation
### npm (Recommended)
```bash
npm install -g google-chat-webhook-mcp
```
### From Source (Development)
```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 Setup
Before configuring the MCP server, create a Google Chat Webhook URL:
1. Open your Google Chat space
2. Menu → "Apps & integrations" → "Manage webhooks"
3. Click "Add webhook"
4. Enter a name and **copy the URL**
5. Use it in the configuration below
## MCP Client Configuration
### 1. Claude Code
#### Config File Location
- **Windows**: `%USERPROFILE%\.claude.json`
- **macOS/Linux**: `~/.claude.json`
**Note**: Claude Desktop uses different paths:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
#### npm Installation
```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"
}
}
}
}
```
#### Source Installation
```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"
}
}
}
}
```
**⚠️ Note**: Use `\\` or `/` for Windows paths (e.g., `C:/path/to/...`)
#### Configuration Scopes
Claude Code supports three configuration scopes:
1. **User Scope** (Global): `~/.claude.json` - Available across all projects
2. **Project Scope** (Shared): `.mcp.json` in project root - Version-controlled, team-shared
3. **Local Scope** (Private): Project-specific, personal settings
**Priority**: Local > Project > User
#### Project-Scoped Configuration (.mcp.json)
For team-shared MCP servers, create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"google-chat": {
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "${GOOGLE_CHAT_WEBHOOK_URL}"
}
}
}
}
```
**Benefits**:
- ✅ Version-controlled with Git
- ✅ Team-shared configuration
- ✅ Environment variable support: `${VAR}` or `${VAR:-default}`
- ✅ Project-specific MCP servers
**Environment Variables**: Each team member can set their own 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"
```
#### How to Apply
**User-scoped configuration** (~/.claude.json):
1. Edit `~/.claude.json` (or `%USERPROFILE%\.claude.json` on Windows)
2. Save the file
3. Restart Claude Code if already running
**Project-scoped configuration** (.mcp.json):
1. Create `.mcp.json` in project root
2. Set environment variables for sensitive data
3. Commit `.mcp.json` to version control
4. Use commands like "Send a message to Google Chat"
### 2. GitHub Copilot (VS Code)
[VS Code GitHub Copilot](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) supports MCP through **agent mode**. Configure MCP servers in workspace or user settings.
#### Configuration File Locations
Choose one of the following:
- **User Settings**: `~/.vscode/settings.json` or `%APPDATA%\Code\User\settings.json` (Windows)
- **Workspace Settings**: `.vscode/settings.json` in your project root
- **Claude Code Config** (Auto-import): Copy from `~/.claude.json`
#### Configuration (mcp.json format)
Add to `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"
}
}
}
}
```
#### Features
- **Agent Mode Integration**: MCP tools available in agent workflow
- **Per-Session Tool Selection**: Choose which tools to enable per session
- **STDIO & SSE Support**: Both transport types supported
- **Debugging**: Restart commands and output logging built-in
#### Using with Agent Mode
1. Open GitHub Copilot Chat in VS Code
2. Enable agent mode (if not already enabled)
3. Start a conversation - Copilot will automatically access MCP tools
4. Tools require approval before execution
**Example:**
```
@workspace Send a deployment summary to Google Chat
```
**📝 Note**: GitHub Copilot's MCP support includes agent mode, allowing sophisticated workflows. Make sure you're using the latest VS Code and GitHub Copilot extension.
### 3. Other MCP Clients
Works with any MCP-compatible client:
```json
{
"command": "npx",
"args": ["-y", "google-chat-webhook-mcp"],
"env": {
"GOOGLE_CHAT_WEBHOOK_URL": "your-webhook-url"
}
}
```
## Usage
### MCP Tools (3 Tools)
Available tools in Claude Code or other MCP clients:
#### 1. `send_google_chat_text`
Send simple text messages
**Example (Claude Code):**
```
Send "Hello from Claude!" to Google Chat
```
**Parameters:**
```json
{
"text": "Hello, Google Chat!"
}
```
#### 2. `send_google_chat_cards_v2`
Send Cards V2 format directly (advanced users)
**Parameters:**
```json
{
"text": "Card Message",
"cardsV2": [
{
"cardId": "unique-card",
"card": {
"header": { "title": "Card Title" },
"sections": [
{
"widgets": [
{ "textParagraph": { "text": "Card content" } }
]
}
]
}
}
]
}
```
#### 3. `send_google_chat_markdown` ⭐ **Recommended**
Convert Markdown to Cards V2 and send
**Example (Claude Code):**
```
Send this markdown to Google Chat:
# Project Update
- Task 1: ✅ Completed
- Task 2: 🚧 In Progress
**Deadline**: Tomorrow
```
**Parameters:**
```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
}
```
**Options:**
- `cardTitle`: Title shown at the top of the card (optional)
- `fallbackToText`: Auto-send as text on conversion failure (default: false)
### Claude Code Usage Example
After setup, Claude will automatically use MCP tools when you chat naturally:
**👤 User:**
> "Send a project status update to Google Chat. Show 3 completed tasks and 2 in-progress tasks as a markdown list."
**🤖 Claude:**
> (Automatically calls `send_google_chat_markdown` tool)
>
> I've sent the message to Google Chat. The project status has been updated.
### Supported Markdown Syntax
Markdown written in Claude or MCP clients is automatically converted to Google Chat Cards V2.
| Syntax | Markdown Example | Google Chat Rendering |
|--------|------------------|----------------------|
| **Headers** | `# H1`, `## H2`, `### H3` | Bold with size differences |
| **Bold** | `**bold**` or `__bold__` | **bold** |
| **Italic** | `*italic*` or `_italic_` | *italic* |
| **Inline Code** | `` `code` `` | `code` (monospace) |
| **Code Block** | ` ```python\ncode\n``` ` | Syntax-highlighted box |
| **Ordered List** | `1. First\n2. Second` | 1. First<br>2. Second |
| **Unordered List** | `- Item` or `* Item` | • Item |
| **Nested List** | ` - nested` (2-space indent) | • nested (Em space) |
| **Table** | `\| A \| B \|\n\|--\|--\|` | Monospace table |
| **Image** | `` | Image widget (after validation) |
| **Link** | `[text](https://...)` | Clickable link |
| **Horizontal Rule** | `---` or `***` | Divider |
| **Blockquote** | `> quote` | Indented + gray text |
**Example 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
```
See [documentation](https://docs.example.com) for details.
```
**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 File (Development)
Create `.env` in project root:
```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
```
## Limitations
### Google Chat API Constraints
| Item | Limit | Workaround |
|------|-------|------------|
| **Image Protocol** | HTTPS only | HTTP URLs replaced with text links |
| **Image Size** | Max 5MB | Show as link on validation failure |
| **Image Auth** | Public URLs only | No access if auth required |
| **Content-Type** | `image/*` only | HTML pages rejected |
| **Markdown Support** | Limited | Unsupported syntax approximated |
### Markdown Conversion Limitations
**✅ Fully Supported:**
- Headers (H1~H6)
- Bold, italic, inline code
- Ordered/unordered lists (up to 3 levels)
- Code blocks (syntax highlighting)
- Tables (monospace)
- Links, images
**⚠️ Partial Support:**
- Complex nesting → Simplified
- HTML tags → Converted to text
- Blockquotes → Shown as indents
**❌ Not Supported:**
- Footnotes
- Definition lists
- Math formulas (LaTeX)
- Task checkboxes (`- [ ]`, `- [x]`)
- Emoji shortcodes (`:smile:`, Unicode emojis work)
## FAQ
### Q: Images not displaying
**A**: Image validation failure causes:
1. **HTTPS only** (HTTP not supported)
2. **File size**: Must be under 5MB
3. **Public access**: Must be accessible without auth
4. **Content-Type**: Response header must be `image/*`
**Debug:**
```bash
cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"
```
### Q: Cards V2 conversion fails
**A**: Use `fallbackToText` option:
```json
{
"markdown": "...",
"fallbackToText": true
}
```
Check logs for details:
```bash
cat logs/errors-YYYY-MM-DD.log
```
### Q: Too many log files
**A**: Adjust with environment variables:
```json
{
"env": {
"LOG_LEVEL": "WARN",
"LOG_RETENTION_DAYS": "7"
}
}
```
### Q: Multiple Google Chat spaces
**A**: Register separate MCP server instances:
```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/..."
}
}
}
}
```
## License
MIT License - [LICENSE](LICENSE)
## Links
- [Model Context Protocol](https://github.com/modelcontextprotocol)
- [Claude Code](https://claude.ai/desktop)
- [Google Chat API](https://developers.google.com/chat)
---
Korean:
[](https://github.com/ice3x2/google-chat-webhook-mcp/actions)
[](https://www.npmjs.com/package/google-chat-webhook-mcp)
[](https://opensource.org/licenses/MIT)
MCP (Model Context Protocol) 서버로 Google Chat 웹훅을 통해 메시지를 전송합니다. 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 스페이스 열기
2. 상단 메뉴 → "앱 및 통합" → "Webhook 관리"
3. "Webhook 추가" 클릭
4. 이름 입력 후 **URL 복사**
5. 아래 설정에서 사용
## MCP 클라이언트 설정
### 1. Claude Code
#### 설정 파일 위치
- **Windows**: `%USERPROFILE%\.claude.json`
- **macOS/Linux**: `~/.claude.json`
**참고**: Claude Desktop은 다른 경로를 사용합니다:
- Windows: `%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는 3가지 설정 스코프를 지원합니다:
1. **User Scope** (전역): `~/.claude.json` - 모든 프로젝트에서 사용 가능
2. **Project Scope** (공유): 프로젝트 루트의 `.mcp.json` - 버전 관리, 팀 공유 가능
3. **Local Scope** (개인): 프로젝트별 개인 설정
**우선순위**: Local > Project > User
#### 프로젝트 수준 설정 (.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`)
2. 파일 저장
3. Claude Code가 실행 중이면 재시작
**Project 수준 설정** (.mcp.json):
1. 프로젝트 루트에 `.mcp.json` 생성
2. 민감한 데이터는 환경 변수로 설정
3. `.mcp.json`을 버전 관리 시스템에 커밋
4. "Send a message to Google Chat" 같은 명령 사용
### 2. GitHub Copilot (VS Code)
[VS Code GitHub Copilot](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode)은 **에이전트 모드**를 통해 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 지원**: 두 전송 방식 모두 지원
- **디버깅**: 재시작 명령 및 출력 로깅 내장
#### 에이전트 모드에서 사용하기
1. VS Code에서 GitHub Copilot 채팅 열기
2. 에이전트 모드 활성화 (기본 활성화된 경우도 있음)
3. 대화 시작 - Copilot이 자동으로 MCP 도구에 접근
4. 도구 실행 전 승인 필요
**예시:**
```
@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):**
```
Send "Hello from Claude!" to Google Chat
```
**파라미터:**
```json
{
"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
```
**파라미터:**
```json
{
"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개를 마크다운 리스트로 작성해서."
**🤖 Claude:**
> (자동으로 `send_google_chat_markdown` 도구 호출)
>
> Google Chat에 메시지를 전송했습니다. 프로젝트 상태가 업데이트되었습니다.
**👤 사용자:**
> "방금 보낸 메시지에 코드 예제도 추가해줘."
**🤖 Claude:**
> (다시 Markdown으로 메시지 생성 및 전송)
### 지원하는 Markdown 문법
Claude나 MCP 클라이언트에서 Markdown으로 메시지를 작성하면 자동으로 Google Chat Cards V2로 변환됩니다.
| 문법 | Markdown 예시 | Google Chat 렌더링 |
|------|---------------|-------------------|
| **헤더** | `# H1`, `## H2`, `### H3` | 굵은 글씨 + 크기 차등 |
| **굵게** | `**bold**` 또는 `__bold__` | **bold** |
| **기울임** | `*italic*` 또는 `_italic_` | *italic* |
| **인라인 코드** | `` `code` `` | `code` (고정폭 폰트) |
| **코드블록** | ` ```python\ncode\n``` ` | 구문 강조 박스 |
| **순서 리스트** | `1. First\n2. Second` | 1. First<br>2. Second |
| **비순서 리스트** | `- Item` 또는 `* 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
```
자세한 내용은 [문서](https://docs.example.com)를 참조하세요.
```
**변환 결과:** 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)
```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만 가능 | 인증 필요 시 접근 불가 |
| **Content-Type** | `image/*`만 허용 | HTML 페이지 등은 거부 |
| **Markdown 지원** | 제한적 | 미지원 문법은 근사치로 변환 |
### Markdown 변환 제약사항
**✅ 완전 지원:**
- 헤더 (H1~H6)
- 굵게, 기울임, 인라인 코드
- 순서/비순서 리스트 (최대 3단계 중첩)
- 코드블록 (구문 강조)
- 표 (고정폭 폰트)
- 링크, 이미지
**⚠️ 부분 지원:**
- 복잡한 중첩 구조 → 단순화됨
- HTML 태그 → 텍스트로 변환
- 인용문 → 들여쓰기로 표현
**❌ 미지원:**
- 각주 (footnotes)
- 정의 리스트 (definition lists)
- 수학 수식 (LaTeX)
- 작업 체크박스 (`- [ ]`, `- [x]`)
- Emoji 단축코드 (`:smile:` 등, 유니코드 이모지는 가능)
### 성능 및 제한
- **이미지 검증 타임아웃**: 5초
- **Webhook 요청 타임아웃**: 5초
- **로그 파일 크기**: 무제한 (30일 자동 삭제)
- **동시 요청**: 제한 없음 (Google Chat API 제한 준수)
### 보안 고려사항
⚠️ **Webhook URL은 민감 정보입니다:**
- Git에 커밋하지 마세요
- 공개 저장소에 노출 금지
- 정기적으로 재생성 권장
- `.env` 파일은 `.gitignore`에 포함 필수
## FAQ
### Q: 이미지가 표시되지 않습니다
**A**: 이미지 URL 검증 실패 원인:
1. **HTTPS만 지원** (HTTP는 불가)
2. **파일 크기**: 5MB 이하여야 함
3. **공개 접근**: 인증 없이 접근 가능한 URL이어야 함
4. **Content-Type**: 응답 헤더가 `image/*`여야 함
**디버깅:**
```bash
# 로그 확인
cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"
```
**검증 실패 시 동작:**
- 이미지는 텍스트 링크로 대체됨
- 예: `⚠️ 이미지 로드 실패: https://... (HTTP 404: Not Found)`
### Q: Cards V2 변환이 실패합니다
**A**: 다음을 확인하세요:
1. **fallbackToText 옵션 사용**:
```json
{
"markdown": "...",
"fallbackToText": true
}
```
변환 실패 시 자동으로 텍스트로 전송됩니다.
2. **로그에서 원인 확인**:
```bash
cat logs/errors-YYYY-MM-DD.log
```
3. **지원하지 않는 Markdown 문법**:
- 각주 (footnotes)
- 정의 리스트 (definition lists)
- 복잡한 HTML 태그
### Q: 로그 파일이 너무 많이 쌓입니다
**A**: 환경 변수로 조정:
```json
{
"env": {
"LOG_LEVEL": "WARN",
"LOG_RETENTION_DAYS": "7"
}
}
```
- `LOG_LEVEL=ERROR`: 에러만 기록
- `LOG_RETENTION_DAYS=7`: 7일만 보관
- `LOG_ENABLE_CONSOLE=false`: 콘솔 출력 비활성화
### Q: npx 실행 시 "command not found" 오류
**A**: Node.js와 npm이 설치되어 있는지 확인:
```bash
node --version # v18.0.0 이상 권장
npm --version
```
설치되지 않았다면:
- **Windows**: https://nodejs.org/ 에서 다운로드
- **macOS**: `brew install node`
- **Linux**: `sudo apt install nodejs npm` (Ubuntu/Debian)
### Q: Webhook URL을 어떻게 안전하게 관리하나요?
**A**:
1. **환경 변수 사용** (설정 파일에 직접 쓰지 마세요)
2. **Git에 커밋하지 마세요** (.gitignore 확인)
3. **정기적으로 재생성** (유출 의심 시)
4. **Google Chat에서 Webhook 삭제**로 무효화 가능
### Q: 여러 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 브랜치)
워크플로우: [`.github/workflows/ci.yml`](.github/workflows/ci.yml)
## 기여
이슈와 PR을 환영합니다!
## 라이선스
MIT License - [LICENSE](LICENSE)
## 문서
- [로깅 설계](docs/logging-design.md)
- [CI 설정 가이드](docs/ci-setup.md)
- [Markdown 구현 계획](docs/markdown-to-cards-implementation.md)
## 관련 프로젝트
- [Model Context Protocol](https://github.com/modelcontextprotocol)
- [Claude Code](https://claude.ai/desktop)
- [Google Chat API](https://developers.google.com/chat)
