기업 위챗 게이트웨이 · MCP Server

오픈소스 MCP(Model Context Protocol) Server로, AI Agent(예: WorkBuddy)가 자연어 명령을 통해 직접 배포한 「기업 위챗 고객 관리 게이트웨이」를 구동할 수 있게 합니다:

• 고객 / 태그 / 콘텐츠 라이브러리 조회

• 기업 그룹 발송 작업 미리보기 및 생성

• 모멘트 SOP 규칙 미리보기 및 생성

• 작업 상태 조회, 작업 취소

⚠️ 이 저장소는 MCP 클라이언트일 뿐입니다. 기업 위챗 백엔드 게이트웨이 자체는 포함하지 않습니다 — 먼저 「기업 위챗 게이트웨이」 백엔드를 직접 배포한 후(아래 「백엔드 게이트웨이 배포(개요)」 참조), 이 저장소로 연결해야 합니다. 모든 실제 전송 동작은 기본적으로 미리보기만 수행하며, 명시적으로 confirm=true를 지정해야 실제로 게이트웨이 API를 호출하여 오조작 그룹 발송을 방지합니다.

아키텍처

┌──────────────┐   stdio + MCP    ┌──────────────────┐   HTTPS (Bearer)   ┌──────────────────────┐
│  AI Agent     │ ───────────────▶ │  wechat-gateway   │ ─────────────────▶ │  企业微信网关后端       │
│ (WorkBuddy)  │                  │  MCP Server       │                    │  (FastAPI 等，自部署)  │
└──────────────┘                  └──────────────────┘                    └──────────────────────┘
                                        ↑
                                   WG_BASE_URL / WG_API_TOKEN
                                   （你的 .env，不提交）

• MCP Server(이 저장소): WG_BASE_URL / WG_API_TOKEN을 읽어 Agent의 의도를 게이트웨이 API 호출로 변환합니다.

• 게이트웨이 백엔드(자체 배포): 기업 위챗 「고객 연락」 API와 연동하여 실제 고객 동기화, 그룹 발송, 모멘트 등을 담당하며, MCP_API_TOKEN으로 이 Server의 신원을 검증합니다.

Related MCP server: wx4py-mcp

기능 및 도구 목록

읽기 전용 / 탐색 유형

동작 유형(기본적으로 미리보기만, confirm=true일 때만 실제 전송)

사전 요구 사항

1. 기업 위챗 게이트웨이 백엔드를 배포하고 다음을 확보:

   • 백엔드 admin API 주소(형식: https://gateway.your-domain.com/api/v1/admin)

   • 백엔드에서 할당한 서비스 토큰 MCP_API_TOKEN

2. 로컬 Python 3.10+

3. MCP를 지원하는 Agent 클라이언트(예: WorkBuddy)

빠른 시작

# 1) 克隆
git clone https://github.com/stevebi88/wecom-gateway-mcp.git
cd wecom-gateway-mcp

# 2) 配置环境变量（复制模板，填入你自己的网关地址与令牌）
cp .env.example .env
#   编辑 .env：
#     WG_BASE_URL=https://gateway.your-domain.com/api/v1/admin
#     WG_API_TOKEN=你网关后端分配的令牌

# 3) 安装并注册到 WorkBuddy（自动建 venv + 装依赖 + 写 mcp.json）
python3 install.py

완료 후 WorkBuddy 왼쪽 「커넥터」에서 wechat-gateway를 찾아 Trust를 클릭하여 활성화합니다. 활성화 후 AI에게 직접 말하세요:

「모든 VIP 태그 고객에게 이 춘분 이벤트 문구를 그룹 발송해줘」

Agent가 자동으로: 태그 찾기 → 인원 추정 → 미리보기 → (확인 후) 그룹 발송 작업 생성.

구성 항목

수동 연동(설치 프로그램 미사용)

WorkBuddy 「커넥터 관리」에서 stdio 유형 MCP를 수동으로 추가:

{
  "mcpServers": {
    "wechat-gateway": {
      "command": "/绝对路径/wechat-gateway-mcp/.venv/bin/python",
      "args": ["/绝对路径/wechat-gateway-mcp/server.py"],
      "env": {
        "WG_BASE_URL": "https://gateway.your-domain.com/api/v1/admin",
        "WG_API_TOKEN": "你网关后端分配的令牌"
      },
      "disabled": false
    }
  }
}

또는 run.sh로 직접 실행(같은 디렉터리의 .env를 읽음).

안전 장치

• 모든 실제 전송(create_group_send / create_moment_rule)은 기본적으로 confirm=false로, 미리보기만 수행하고 전송하지 않습니다.

• Agent가 명시적으로 confirm=true를 지정할 때만 실제로 게이트웨이 API를 호출합니다.

• 게이트웨이 백엔드는 MCP_API_TOKEN 서비스 토큰으로 인증합니다; 이 Server와 토큰은 사용자 소유의 게이트웨이와 로컬 사이에서만 사용됩니다.

• .env에 토큰이 포함되어 있으며 .gitignore로 무시됩니다. 안전하게 보관하고 절대 커밋하거나 유출하지 마세요.

백엔드 게이트웨이 배포(개요)

백엔드 코드는 이 저장소에 없습니다. 아래는 이 MCP가 연결하는 게이트웨이의 참조 아키텍처로, 직접 구축하거나 환경을 확인하는 데 도움이 됩니다.

권장 스택(예시): FastAPI(ASGI) + gunicorn + Nginx + Redis + SQLAlchemy, Python 3.12.

백엔드가 제공해야 할 핵심 기능 / 구성:

• 기업 위챗 「고객 연락」 관련 자격 증명(corpid / secret / agentid 등)은 백엔드가 직접 보관하며, 이 MCP 저장소에 넣지 마세요.

• admin API 노출(이 Server가 호출하는 각 경로: /accounts, /tags, /contacts, /contents, /group_send/*, /moment/*, /media/{id}/media_id 등).

• 백엔드 .env에 MCP_API_TOKEN이 필요하며, 그 값은 이 Server의 WG_API_TOKEN과 일치해야 호출자 신원을 검증할 수 있습니다.

• 미디어 자료는 객체 스토리지(예: COS)로 이전하는 것을 권장하며, resolve_content가 media_id를 가져올 때 자료 만료로 실패하는 것을 방지합니다.

배포 후 admin 기본 주소와 MCP_API_TOKEN을 확보하여 이 저장소의 .env에 입력하면 됩니다.

알려진 데이터 문제

과거 마이그레이션 자료가 객체 스토리지로 이전되지 않은 경우, 이미지/비디오 유형 전송 시 resolve_content가 media_id를 가져올 때 「자료 만료」 오류가 발생할 수 있습니다. 순수 텍스트 / 링크 전송은 영향을 받지 않습니다; 이미지 유형 전송은 백엔드에서 자료를 다시 업로드하거나 객체 스토리지로 이전해야 합니다.

라이선스

MIT