whatsmcp

Cloudflare Workers에서 실행되는 상태 비저장 MCP 서버로, Z-API WhatsApp REST API를 도구로 노출하며, Streamable HTTP를 통해 https://whatsmcp.unfld.dev/mcp에서 제공됩니다.

도구는 빌드 시점에 postman.json에서 생성되므로, 도구 표면은 수동으로 유지 관리되지 않고 컬렉션을 추적합니다. 세 가지 메타 도구(zapi_list_endpoints, zapi_describe_endpoint, zapi_request)는 항상 등록되므로, 도구 세트 필터가 노출 대상을 좁히더라도 어떤 엔드포인트도 접근 불가능한 상태가 되지 않습니다.

설정

bun install

저장소 루트에 .dev.vars 파일을 생성하고(gitignore 처리됨) Z-API 자격 증명을 입력합니다:

MCP_AUTH_TOKEN=...
ZAPI_INSTANCE_ID=...
ZAPI_INSTANCE_TOKEN=...
ZAPI_CLIENT_TOKEN=...

ZAPI_INSTANCE_ID와 ZAPI_INSTANCE_TOKEN은 인스턴스 기본 URL을 구성하고, ZAPI_CLIENT_TOKEN은 Client-Token 헤더로 전송됩니다. MCP_AUTH_TOKEN은 클라이언트가 제시해야 하는 정적 Bearer 토큰입니다.

Related MCP server: WA MCP

로컬 실행

bun run dev

Wrangler는 Worker를 http://localhost:8787에서 제공합니다. MCP 엔드포인트는 http://127.0.0.1:8787/mcp입니다. 클라이언트는 다음 중 하나를 전송해야 합니다:

Authorization: Bearer <MCP_AUTH_TOKEN>
Authorization: <MCP_AUTH_TOKEN>

GET /health는 공개이며 { "ok": true, "name": "whatsmcp" }를 반환합니다.

스크립트

바인딩이나 변수를 wrangler.jsonc에서 변경한 후에는 bun run cf-typegen을 다시 실행하세요.

설정

ZAPI_TOOLSETS (wrangler.jsonc의 일반 변수, 기본값 *)는 도구로 등록할 Z-API 카테고리를 선택합니다. 예: instance,messages,groups. 메타 도구는 이 필터를 무시합니다.

배포

비밀 값은 wrangler.jsonc에 저장되지 않습니다. 환경별로 한 번씩 설정하세요:

wrangler secret put MCP_AUTH_TOKEN
wrangler secret put ZAPI_INSTANCE_ID
wrangler secret put ZAPI_INSTANCE_TOKEN
wrangler secret put ZAPI_CLIENT_TOKEN
wrangler deploy

whatsmcp.unfld.dev 사용자 정의 도메인은 wrangler.jsonc에 선언되어 있으며, 첫 배포 시 Cloudflare에서 프로비저닝됩니다.

클라이언트 연결

{
  "mcpServers": {
    "whatsmcp": {
      "url": "https://whatsmcp.unfld.dev/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

Authorization: Bearer <MCP_AUTH_TOKEN>과 Bearer 없는 Authorization: <MCP_AUTH_TOKEN> 형식 모두 허용됩니다. GET /health는 공개이며 가동 시간 확인을 위해 인증이 필요하지 않습니다.