WeCom (WeChat Work) 봇을 위한 Model Context Protocol (MCP) 준수 서버 구현체입니다.

다양한 메시지 유형 지원:
Markdown 메시지 (@mention 및 글자 색상 포함)
Markdown V2 메시지 (표, 리스트, 임베디드 이미지 포함)
이미지 메시지 (base64/로컬 파일/URL)
파일 메시지
템플릿 카드 메시지 (text_notice 및 news_notice)

멀티 봇 지원: 여러 개의 WeCom 봇을 구성하고 사용 가능

@mention 지원 (사용자 ID 또는 전화번호를 통해)
메시지 기록 추적
설정 가능한 로깅 시스템
완전한 타입 어노테이션 (Type annotations)
Pydantic 기반 데이터 검증
Python 3.10+
WeCom 봇 Webhook URL (WeCom 그룹 설정에서 획득)

WeCom Bot MCP Server를 설치하는 방법은 여러 가지가 있습니다:

npx -y @smithery/cli install wecom-bot-mcp-server --client claude

VSCode 마켓플레이스에서 Cline Extension 설치
명령 팔레트(Command Palette) 열기 (Ctrl+Shift+P / Cmd+Shift+P)
"Cline: Install Package" 검색
"wecom-bot-mcp-server"를 입력하고 Enter 누르기

MCP 클라이언트 설정 파일에 서버를 추가하세요:

// macOS의 Claude Desktop용: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows의 Claude Desktop용: %APPDATA%\Claude\claude_desktop_config.json
// Windsurf용: ~/.windsurf/config.json
...

# Windows PowerShell
$env:WECOM_WEBHOOK_URL = "your-webhook-url"
# 선택적 설정
...

다음 방법 중 하나를 사용하여 여러 봇을 구성할 수 있습니다:

방법 1: JSON 설정 (권장)

# Windows PowerShell
$env:WECOM_BOTS = '{"alert": {"name": "Alert Bot", "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx", "description": "For alerts"}, "ci": {"name": "CI Bot", "webhook_url": "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy", "description": "For CI/CD"}}'
# Linux/macOS
...

방법 2: 개별 환경 변수

Windows PowerShell

$env:WECOM_BOT_ALERT_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=xxx"
$env:WECOM_BOT_CI_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=yyy"
...

방법 3: 결합 모드 (Combined Mode)

# WECOM_WEBHOOK_URL이 '기본(default)' 봇으로 설정됩니다.
$env:WECOM_WEBHOOK_URL = "https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=default"
# 추가 봇
...

{
"mcpServers": {
"wecom": {
...

로깅 시스템은 크로스 플랫폼 로그 파일 관리를 위해 platformdirs.user_log_dir()를 사용합니다:

Windows:
C:\Users\<사용자 이름>\AppData\Local\hal\wecom-bot-mcp-server\Logs
Linux:
~/.local/state/hal/wecom-bot-mcp-server/log
macOS:
~/Library/Logs/hal/wecom-bot-mcp-server

로그 파일은 mcp_wecom.log라는 이름으로 위 디렉터리에 저장됩니다.

환경 변수를 사용하여 로그 레벨과 파일 경로를 사용자 정의할 수 있습니다:

MCP_LOG_LEVEL :DEBUG, INFO, WARNING, ERROR, 또는 CRITICAL로 설정 MCP_LOG_FILE :사용자 지정 로그 파일 경로로 설정

설정 후에는 MCP 서버가 MCP 클라이언트 시작 시 자동으로 실행됩니다. AI 비서에서 자연어로 상호 작용할 수 있습니다.

시나리오 1: WeCom으로 날씨 정보 전송

USER: "오늘 선전의 날씨는 어때? WeCom으로 보내줘"
ASSISTANT: "선전의 날씨를 확인하고 WeCom으로 보낼게요"
[어시스턴트는 send_message 도구를 사용하여 날씨 정보를 전송할 것입니다]

시나리오 2: 회의 알림 및 관련 인원 @멘션하기

USER: "오후 3시 프로젝트 검토 회의 알림을 보내고, 장산과 리사에게 참석하라고 알려줘"
ASSISTANT: "회의 알림을 보낼게요"
[어시스턴트는 mentioned_list 매개변수를 사용하여 send_message 도구를 사용할 것입니다]

시나리오 3: 파일 전송

USER: "이 주간 보고서를 WeCom 그룹에 보내줘"
ASSISTANT: "주간 보고서를 보낼게요"
[어시스턴트는 send_file 도구를 사용할 것입니다]

시나리오 4: 이미지 전송

USER: "이 차트 이미지를 WeCom으로 보내줘"
ASSISTANT: "이미지를 보낼게요"
[어시스턴트는 send_image 도구를 사용할 것입니다]

서버는 귀하의 AI 어시스턴트가 사용할 수 있는 다음과 같은 도구들을 제공합니다:

send_message- 텍스트 또는 마크다운 (markdown) 메시지 전송

매개변수 (Parameters):
content
, msg_type
(markdown/markdown_v2), mentioned_list
, mentioned_mobile_list
, bot_id

markdown: 콘텐츠에 <@userid> 멘션이나 글자 색상이 포함된 경우 사용합니다. <@userid> 구문은 WeCom의 공식 멘션 형식으로, @user@email.com과 같은 이메일 주소와의 충돌을 방지합니다.

markdown_v2: 표 (tables), 리스트 (lists), 임베디드 이미지 (embedded images) 또는 일반 콘텐츠에 사용합니다 (기본값).

매개변수 (Parameters):

send_wecom_file- WeCom으로 파일 전송

매개변수 (Parameters):
file_path
, bot_id
매개변수 (Parameters):

send_wecom_image- WeCom으로 이미지 전송

매개변수 (Parameters):
image_path
(로컬 경로 또는 URL), bot_id
매개변수 (Parameters):

send_wecom_template_card_text_notice- 텍스트 공지 템플릿 카드 전송

매개변수 (Parameters):
template_card_source
, template_card_main_title
, template_card_card_action
, bot_id
, 그리고 선택적 필드들 - 강조된 콘텐츠, 인용구, 액션 버튼이 포함된 알림에 사용합니다.
매개변수 (Parameters):

send_wecom_template_card_news_notice- 뉴스 공지 템플릿 카드 전송

매개변수 (Parameters):
template_card_source
, template_card_main_title
, template_card_card_action
, template_card_image
, bot_id
, 그리고 선택적 필드들 - 이미지와 풍부한 콘텐츠가 포함된 뉴스 스타일의 알림에 사용합니다.
매개변수 (Parameters):

list_wecom_bots- 구성된 모든 봇 목록 나열

반환값 (Returns): ID, 이름, 설명이 포함된 사용 가능한 봇 목록

시나리오 5: 특정 봇에게 알림 전송

USER: "알람 봇에게 긴급 알림을 보내줘: 서버 CPU 사용량이 90%를 초과했습니다"
ASSISTANT: "알람 봇에게 알림을 보낼게요"
[어시스턴트는 bot_id="alert"와 함께 send_message를 사용할 것입니다]

시나리오 6: 사용 가능한 봇 목록 나열

USER: "사용 가능한 WeCom 봇은 무엇인가요?"
ASSISTANT: "사용 가능한 봇을 확인하겠습니다"
[시스턴트는 list_wecom_bots 도구를 사용할 것입니다]

시나리오 7: CI 알림 전송

USER: "CI 봇에게 빌드 성공 알림을 보내줘"
ASSISTANT: "CI 봇에게 알림을 보내겠습니다"
[시스턴트는 bot_id="ci"와 함께 send_message를 사용할 것입니다]

시나리오 8: 템플릿 카드 알림 전송

USER: "대시보드 링크가 포함된 배포 성공 알림 카드를 보내줘"
ASSISTANT: "템플릿 카드 알림을 보내겠습니다"
[시스턴트는 send_wecom_template_card_text_notice 도구를 사용할 것입니다]

시나리오 9: 뉴스 스타일 알림 전송

USER: "이미지가 포함된 신규 기능 출시 관련 뉴스 카드를 보내줘"
ASSISTANT: "뉴스 공지 카드를 보내겠습니다"
[시스턴트는 send_wecom_template_card_news_notice 도구를 사용할 것입니다]

이 패키지를 (MCP 서버가 아닌) Python 코드에서 직접 사용하려면:

from wecom_bot_mcp_server import send_message, send_wecom_file, send_wecom_image, send_wecom_template_card
# 마크다운 메시지 전송 (기본 봇 사용)
await send_message(
...

from wecom_bot_mcp_server.bot_config import get_bot_registry, list_available_bots
# 사용 가능한 모든 봇 목록 나열
bots = list_available_bots()
...

저장소(Repository) 클론:

git clone https://github.com/loonghao/wecom-bot-mcp-server.git
cd wecom-bot-mcp-server

가상 환경(Virtual Environment) 생성 및 의존성 설치:

# uv 사용 (권장)
pip install uv
uv venv
...

# 커버리지(Coverage)와 함께 모든 테스트 실행
uvx nox -s pytest
# 임포트(Import) 테스트만 실행
...

# 코드 검사
uvx nox -s lint
# 코드 스타일 이슈 자동 수정
...

# 패키지 빌드
uvx nox -s build
# PyPI에 배포 (인증 필요)
...

이 프로젝트는 CI/CD를 위해 GitHub Actions를 사용합니다:

MR Checks: 모든 Pull Request (PR)에서 실행되며, Python 3.10, 3.11, 3.12 환경의 Ubuntu, Windows, macOS에서 테스트를 수행합니다.
Code Coverage: Codecov에 코드 커버리지 (Code Coverage) 보고서를 업로드합니다.
Import Tests: 설치 후 패키지가 올바르게 임포트 (Import)되는지 확인합니다.

모든 의존성 (Dependencies)은 문제를 조기에 발견하기 위해 CI 과정에서 자동으로 테스트됩니다.

wecom-bot-mcp-server/
├── src/
│ └── wecom_bot_mcp_server/
...

이 프로젝트는 MIT 라이선스 (MIT License) 하에 배포됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

저자 (Author): longhao
이메일 (Email): hal.long@outlook.com

loonghao/wecom-bot-mcp-server

요약

핵심 포인트

Windows PowerShell

댓글