mcp-wb

원격 MCP 서버로서 Claude를 Wildberries에서 구매자와의 소통(리뷰, 질문, 채팅)에 연결합니다. 조직 맞춤 커넥터로 배포되며, 각 직원은 자신의 Claude에서 연결하고 Wildberries 토큰은 서버에만 남습니다.

기능

읽기

고객 응답 — 초안을 통해서만

모든 전송은 직원 이메일, 텍스트, 결과와 함께 audit 로그에 기록됩니다.

Related MCP server: Meta Cloud API MCP Server

이렇게 구성한 이유

Wildberries 토큰은 개인용이며 서버를 벗어나지 않습니다. 기본 토큰의 WB 카테고리 한도는 '질문 및 리뷰'가 시간당 5회, 채팅이 시간당 1회라서 실무에 쓸 수 없습니다. 개인 토큰은 초당 3회 요청을 허용하지만, WB 규정상 제3자에게 전달하거나 클라우드 서비스에서 사용할 수 없으며, 자체 또는 임대 인프라의 시스템용으로 설계되었습니다. 따라서 자체 VPS, 서버에 토큰 하나, 직원들은 OAuth를 통해 접근합니다.

직원 신원은 우리 서버가 확인합니다. Claude는 MCP 서버에 이메일이나 사용자 ID를 전달하지 않으며, 조직 관리 콘솔도 '인증 없는 서버' 옵션을 지원하지 않습니다. 따라서 서버 자체가 OAuth 2.1 인가 서버(PKCE, Dynamic Client Registration, RFC 9728/8414)로 동작하고, 신원은 Google, Yandex 또는 일회용 코드에서 가져옵니다.

역할. ALLOWED_EMAIL_DOMAINS / ALLOWED_EMAILS는 누가 들어올 수 있는지 결정합니다. RESPONDER_EMAILS와 ADMIN_EMAILS는 누가 보낼 수 있는지 결정합니다. 나머지 사람들은 wb:write 권한이 없는 토큰을 받아 물리적으로 wb_draft_send를 호출할 수 없습니다.

요구 사항

• 인터넷에서 접근 가능한 공인 IP를 가진 VPS(Claude가 자체 네트워크에서 서버에 접속하므로 NAT 또는 VPN 뒤의 서버는 사용할 수 없음)

• 이 IP로 A 레코드가 연결된 도메인

• Docker 및 Docker Compose

• '질문 및 리뷰'와 '구매자 채팅' 카테고리가 있는 WB 개인 토큰

• Claude 조직에서 Owner 또는 Primary Owner 권한(커넥터를 추가할 수 있는 사람은 이들뿐)

배포

1. Wildberries 토큰

판매자 개인 계정 → 설정 → API 액세스 → 토큰 만들기 → '수동 통합용' 탭 → 유형 개인. '질문 및 리뷰' 및 '구매자 채팅' 카테고리를 선택하고 액세스 수준은 읽기 및 쓰기로 설정합니다. 토큰은 한 번만 표시되며 180일 동안 유효하므로 교체 알림을 설정하세요.

2. 구성

git clone <репозиторий> mcp-wb && cd mcp-wb
cp .env.example .env

.env를 작성하세요. 필수 최소 항목:

PUBLIC_URL=https://mcp-wb.вашдомен.ru
MCP_DOMAIN=mcp-wb.вашдомен.ru
ACME_EMAIL=admin@вашдомен.ru
WB_TOKEN=<токен из шага 1>
SESSION_SECRET=<openssl rand -hex 32>
ALLOWED_EMAIL_DOMAINS=вашдомен.ru
ADMIN_EMAILS=вы@вашдомен.ru
RESPONDER_EMAILS=менеджер1@вашдомен.ru,менеджер2@вашдомен.ru

실행 전에 토큰을 확인하세요:

npm install && npx tsx scripts/probe-wb.ts

3. 직원 로그인

Google Workspace(IDENTITY_PROVIDER=google) — Google Cloud Console에서 '웹 애플리케이션' 유형의 OAuth 클라이언트를 만들고 Authorized redirect URIs에 다음을 추가하세요:

https://mcp-wb.вашдомен.ru/idp/google/callback

GOOGLE_CLIENT_ID 및 GOOGLE_CLIENT_SECRET은 .env에 넣습니다.

Yandex ID(IDENTITY_PROVIDER=yandex) — oauth.yandex.ru의 앱, Callback URI:

https://mcp-wb.вашдомен.ru/idp/yandex/callback

외부 IdP 없이(IDENTITY_PROVIDER=invite) — 일회용 코드를 발급하세요:

docker compose exec mcp-wb node dist/scripts/invite.js ivan@вашдомен.ru

4. 실행

docker compose up -d --build

Caddy가 Let's Encrypt 인증서를 자동으로 획득합니다. 확인:

curl https://mcp-wb.вашдомен.ru/.well-known/oauth-protected-resource/mcp

"resource": "https://mcp-wb.вашдомен.ru/mcp"가 포함된 JSON이 반환되어야 합니다.

5. Claude 조직에 연결

1. 조직의 Settings → Connectors(이 항목은 Owner에게만 표시됩니다).

2. Add → Custom → Web.

3. URL: https://mcp-wb.вашдомен.ru/mcp

4. Advanced settings는 건드릴 필요가 없습니다. 서버가 Dynamic Client Registration을 지원하므로 Claude를 자체적으로 등록합니다.

5. 저장하면 커넥터가 조직의 모든 직원에게 나타납니다.

6. 각 직원이 수행할 작업

Claude를 열고 → Connectors → 커넥터를 찾아서 → Connect → 회사 이메일로 로그인합니다. 그 후에는 자연어로 '지난주 답변하지 않은 리뷰를 보여줘', '리뷰 X에 대한 답변을 준비해줘'라고 작성하면 됩니다.

자신의 권한을 확인하려면: wb_whoami.

운영

작업 로그. 구매자에게 전송된 모든 내용은 데이터베이스 파일의 audit 테이블에 저장됩니다:

docker compose exec mcp-wb \
  node -e "const d=require('better-sqlite3')('/data/mcp-wb.db');console.table(d.prepare('SELECT datetime(ts,\"unixepoch\") t,actor,action,target,outcome FROM audit ORDER BY ts DESC LIMIT 30').all())"

직원의 액세스 권한 취소 — ALLOWED_EMAILS에서 제거하거나 Google Workspace에서 비활성화한 후 컨테이너를 다시 시작하세요. 유효한 토큰은 모든 요청 시 액세스 목록을 확인하므로 권한이 즉시 사라집니다.

WB 토큰 교체 — 180일마다: .env에 새 토큰을 입력한 후 docker compose … up -d를 실행합니다.

한도. 클라이언트가 자체적으로 속도를 조절합니다: 리뷰 및 질문은 초당 3회, 채팅은 10초에 10회이며, 429 응답 시 X-Ratelimit-Retry 헤더에 따라 대기합니다.

개발

npm install
npm run dev          # tsx watch
npm run typecheck
WB_SANDBOX=true npm run dev   # песочница WB (только отзывы и вопросы, чата в ней нет)

로컬 OAuth 테스트를 위해 PUBLIC_URL=http://localhost:3000 및 IDENTITY_PROVIDER=invite를 설정하세요.

한계

• 채팅: WB에는 샌드박스 호스트가 없으므로 실계정에서만 테스트할 수 있습니다.

• 리뷰 및 질문에 대한 답변은 WB의 검수를 거쳐 즉시 게시되지 않습니다.

• 답변 수정은 60일 동안 한 번만 가능하며, 이후 텍스트는 영구적으로 고정됩니다.

• 반품 요청(returns-api)은 별도의 토큰 카테고리가 필요하며 이 버전에서는 연결되어 있지 않습니다.

• 서버는 세션 없이 작동합니다. 각 HTTP 요청마다 MCP 서버 인스턴스가 생성되므로 클라이언트로 향하는 서버 알림이 없습니다.