mcp-wb

Remote MCP server that connects Claude to communication with buyers on Wildberries: reviews, questions, and chats. Deployed as a custom organization connector — each employee connects it in their own Claude, while the Wildberries token stays only on the server.

What it can do

Reading

Replies to customers — only via draft

Every send is written to the audit log with the employee's email, text, and result.

Related MCP server: Meta Cloud API MCP Server

Why it is structured this way

The Wildberries token is personal, and it never leaves the server. WB limits for the "Questions and Reviews" category for a basic token are 5 requests per hour, for chats — 1 request per hour; you cannot work with those. A personal token gives 3 requests per second, but per WB rules it is forbidden to share it with third parties or use it in cloud services — it is intended for systems on your own or rented infrastructure. Hence: your own VPS, one token on the server, employees go through OAuth.

The employee's identity is established by our server. Claude does not pass email or user ID to the MCP server, and the organization admin panel does not support the "server without authorization" option. So the server itself works as an OAuth 2.1 authorization server (PKCE, Dynamic Client Registration, RFC 9728/8414), and takes identity from Google, Yandex, or a one-time code.

Roles. ALLOWED_EMAIL_DOMAINS / ALLOWED_EMAILS decide who can log in at all. RESPONDER_EMAILS and ADMIN_EMAILS — who can send. Everyone else gets a token without the wb:write right and physically cannot call wb_draft_send.

Requirements

• VPS with a public IP, reachable from the internet (Claude reaches the server from its side — a server behind NAT or VPN will not work)

• Domain with an A-record pointing to this IP

• Docker and Docker Compose

• Personal WB token with the "Questions and Reviews" and "Chat with buyers" categories

• Owner or Primary Owner rights in the Claude organization (only they can add connectors)

Deployment

1. Wildberries token

Seller's personal account → Settings → API Access → Create token → "For manual integration" tab → type Personal. Check the "Questions and Reviews" and "Chat with buyers" categories, access level — Read and write. The token is shown once, lives 180 days — set a reminder to replace it.

2. Configuration

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

Fill in .env. Required minimum:

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

Check the token before starting:

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

3. Employee login

Google Workspace (IDENTITY_PROVIDER=google) — in Google Cloud Console create an OAuth client of type "Web application", in Authorized redirect URIs add:

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

GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET — in .env.

Yandex ID (IDENTITY_PROVIDER=yandex) — app at oauth.yandex.ru, Callback URI:

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

Without external IdP (IDENTITY_PROVIDER=invite) — issue one-time codes:

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

4. Launch

docker compose up -d --build

Caddy will get the Let's Encrypt certificate itself. Check:

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

Should return JSON with "resource": "https://mcp-wb.вашдомен.ru/mcp".

5. Connecting to the Claude organization

1. Settings → Connectors in the organization (the item is visible only to Owner).

2. Add → Custom → Web.

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

4. No need to touch Advanced settings: the server supports Dynamic Client Registration and will register Claude itself.

5. Save — the connector appears for all organization employees.

6. What each employee does

Opens Claude → Connectors → finds the connector → Connect → logs in with corporate email. After that you can write in plain language: "show unanswered reviews for the week", "prepare a reply to review X".

Check your rights: wb_whoami.

Operations

Action log. Everything that went to the buyer is stored in the audit table of the database file:

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())"

Revoke an employee's access — remove them from ALLOWED_EMAILS / disable them in Google Workspace and restart the container. Active tokens check the access list on every request, so access disappears immediately.

Replacing the WB token — once every 180 days: new token in .env, then docker compose … up -d.

Limits. The client itself keeps the pace: 3 requests/s for reviews and questions, 10 per 10 s for chats, with waiting on the X-Ratelimit-Retry header on 429.

Development

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

For a local OAuth run, set PUBLIC_URL=http://localhost:3000 and IDENTITY_PROVIDER=invite.

Boundaries

• Chat: WB has no sandbox host, you can only test on the production account.

• Replies to reviews and questions go through WB moderation and are not published instantly.

• Editing a reply — one attempt within 60 days, after that the text is fixed forever.

• Return requests (returns-api) require a separate token category and are not connected in this version.

• The server works without sessions: each HTTP request creates its own MCP server instance, so there are no server-side notifications to the client.