waxum-mcp

WhatsApp용 MCP 서버로, waxum REST API 게이트웨이를 기반으로 합니다. stdio를 통해 모든 MCP 클라이언트(Claude Desktop, Claude Code 등)에 전송/읽기/미디어 도구를 제공합니다.

waxum >= 0.11.5가 필요합니다(GET /messages/chat/{chat_jid} 필요).

세션 페어링(QR/전화번호 연결)은 이 서버의 일부가 아닙니다 — 먼저 waxum에 직접 세션을 페어링하고(자체 콘솔 또는 POST /sessions/{id}/pair), 그런 다음 이 서버를 이미 페어링된 세션에 연결하세요.

도구

Related MCP server: mcp-wacli

구성

이 서버를 waxum에 연결하는 두 가지 방법이 있으며, WAXUM_MODE로 선택합니다(또는 자동 감지: WAXUM_BASE_URL이 설정된 경우 client, 그렇지 않으면 spawn).

클라이언트 모드 — waxum이 다른 곳에서 이미 실행 중인 경우

WAXUM_MODE=client
WAXUM_BASE_URL=http://localhost:3451
WAXUM_TOKEN=<superadmin token or a session token>
WAXUM_SESSION_ID=<the session to operate on>
WAXUM_MEDIA_DIR=./media   # optional, default ./media

스폰 모드 — 이 서버가 waxum 프로세스를 관리

WAXUM_MODE=spawn
WAXUM_BINARY_PATH=/path/to/waxum
WAXUM_WORKDIR=/path/to/waxum/data   # optional, default: binary's directory
WAXUM_PORT=3451                     # optional, default 3451
WAXUM_TOKEN=<superadmin token>      # optional, a random one is generated if unset
WAXUM_SESSION_ID=<the session to operate on>
WAXUM_DATABASE_URL=sqlite:///data/waxum.db # optional

스폰 모드에서 토큰은 생성된 프로세스의 SUPERADMIN_TOKEN 환경 변수가 됩니다 — waxum 자체의 부트스트랩 자격 증명 — 따라서 토큰을 미리 발급할 필요가 없습니다. 하위 프로세스의 stdout과 stderr는 이 서버의 stderr로 전달됩니다(MCP 프로토콜 채널용으로 예약된 stdout으로는 절대 전달되지 않습니다).

스폰 모드는 기본적으로 <WAXUM_WORKDIR>/waxum.db에 SQLite를 사용하므로 MCP 서버가 별도 구성 없이 재시작에도 안전합니다. 필요 시 WAXUM_DATABASE_URL을 명시적인 sqlite:// 경로, PostgreSQL URL 또는 MySQL URL로 설정하세요.

개발

npm install
npm run dev     # run directly with tsx
npm run build   # compile to dist/
npm start       # run the compiled build