---

Google Chat Webhook MCP Server

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)

npm install -g google-chat-webhook-mcp

From Source (Development)

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

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

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

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

# 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 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:

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

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

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

2. send_google_chat_cards_v2

Send Cards V2 format directly (advanced users)

Parameters:

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

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

# 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 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:

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:

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

Q: Cards V2 conversion fails

A: Use fallbackToText option:

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

Check logs for details:

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

Q: Too many log files

A: Adjust with environment variables:

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

Q: Multiple Google Chat spaces

A: Register separate MCP server instances:

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

Links

• Model Context Protocol
• Claude Code
• Google Chat API

---

Korean:

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 설치 (권장)

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을 생성해야 합니다:

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 설치 시

{
  "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는 3가지 설정 스코프를 지원합니다:

1. User Scope (전역): ~/.claude.json - 모든 프로젝트에서 사용 가능
2. Project Scope (공유): 프로젝트 루트의 .mcp.json - 버전 관리, 팀 공유 가능
3. Local Scope (개인): 프로젝트별 개인 설정

우선순위: Local > Project > User

프로젝트 수준 설정 (.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):

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은 에이전트 모드를 통해 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 지원: 두 전송 방식 모두 지원
• 디버깅: 재시작 명령 및 출력 로깅 내장

에이전트 모드에서 사용하기

1. VS Code에서 GitHub Copilot 채팅 열기
2. 에이전트 모드 활성화 (기본 활성화된 경우도 있음)
3. 대화 시작 - Copilot이 자동으로 MCP 도구에 접근
4. 도구 실행 전 승인 필요

예시:

@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):**

Send "Hello from Claude!" to Google Chat

**파라미터:**
```json
{
  "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개를 마크다운 리스트로 작성해서."

🤖 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:

# 프로젝트 배포 완료 🚀

## 주요 변경사항

- **성능 개선**: 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)

```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만 가능	인증 필요 시 접근 불가
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/*여야 함

디버깅:

# 로그 확인
cat logs/app-YYYY-MM-DD.log | grep "image_validation_failed"

검증 실패 시 동작:

• 이미지는 텍스트 링크로 대체됨
• 예: ⚠️ 이미지 로드 실패: https://... (HTTP 404: Not Found)

Q: Cards V2 변환이 실패합니다

A: 다음을 확인하세요:

1. fallbackToText 옵션 사용:

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

   변환 실패 시 자동으로 텍스트로 전송됩니다.

2. 로그에서 원인 확인:

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

3. 지원하지 않는 Markdown 문법:

   • 각주 (footnotes)
   • 정의 리스트 (definition lists)
   • 복잡한 HTML 태그

Q: 로그 파일이 너무 많이 쌓입니다

A: 환경 변수로 조정:

{
  "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이 설치되어 있는지 확인:

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 서버 인스턴스 등록:

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

기여

이슈와 PR을 환영합니다!

라이선스

MIT License - LICENSE

문서

• 로깅 설계
• CI 설정 가이드
• Markdown 구현 계획

관련 프로젝트

• Model Context Protocol
• Claude Code
• Google Chat API