WildberriesToolsMCP

MCP server for retrieving Wildberries product reviews and exposing them to LLM clients.

The server supports:

• stdio for local MCP clients such as Claude Desktop, Cursor, and Cherry Studio;
• Streamable HTTP for remote MCP clients such as ChatGPT custom MCP apps;
• optional rotating VLESS egress through Xray-core for deployments whose normal outbound IP is unsuitable for Wildberries access.

Tool

Tool	Description
get_wb_reviews	Accepts a Wildberries product URL or SKU and returns product metadata plus up to 500 review texts as JSON.

Architecture

Without Xray:

ChatGPT / MCP client
        |
        v
WildberriesToolsMCP
        |
        v
Wildberries APIs

With rotating VLESS egress:

ChatGPT / MCP client
        |
        v
WildberriesToolsMCP
        |
        | HTTPX SOCKS5
        v
127.0.0.1:1080
        |
        v
Xray-core
        |
        | validated VLESS candidate
        v
Wildberries APIs

The MCP endpoint itself is not proxied through VLESS. Only outbound HTTP requests made by the Wildberries client use OUTBOUND_PROXY.

VLESS rotation lifecycle

When XRAY_ENABLED=true, the container supervisor starts the Xray rotator before the MCP server:

1. Download the configured vless:// subscription.

2. Extract and shuffle unique VLESS candidates.

3. Convert a candidate into Xray JSON.

4. Validate the generated configuration with:

   xray run -test -config candidate.json
   

5. Start the candidate on a temporary SOCKS port (1081).

6. Make a real HTTP request to XRAY_VALIDATION_URL through that Xray process.

7. Activate only candidates that pass both Xray syntax validation and the live HTTP probe.

8. Serve the selected route on 127.0.0.1:1080.

9. Health-check the active route periodically and rotate after repeated failures.

10. Refresh the subscription and rotate the exit periodically.

The default Docker Compose and Render configurations use:

https://raw.githubusercontent.com/igareck/vpn-configs-for-russia/main/BLACK_VLESS_RUS_mobile.txt

The source is external to this project. Override XRAY_SUBSCRIPTION_URL with your own trusted VLESS feed when needed.

The current parser supports the common subscription shapes used by that feed:

• VLESS + REALITY + TCP;
• VLESS + TLS + WebSocket;
• VLESS + TLS + XHTTP;
• VLESS + gRPC;
• VLESS + HTTPUpgrade.

Unsupported or malformed candidates are skipped automatically.

Requirements

For direct Python usage:

• Python 3.10+;
• pip.

For the bundled Xray deployment:

• Docker or a Docker-compatible hosting platform.

The Docker image currently pins Xray-core 26.3.27 instead of using an unpinned latest binary.

Local installation

git clone https://github.com/Happyfunnysad/WildberriesToolsMCP.git
cd WildberriesToolsMCP
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Run over stdio

stdio remains the default transport for direct Python execution:

python server.py

Equivalent explicit configuration:

MCP_TRANSPORT=stdio python server.py

Example client configuration:

{
  "mcpServers": {
    "wildberries-tools": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/WildberriesToolsMCP/server.py"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

On Windows, use the full path to .venv\\Scripts\\python.exe.

Run over Streamable HTTP

Direct Python process without Xray:

MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 \
MCP_PORT=8000 \
MCP_PATH=/mcp \
python server.py

The MCP endpoint will be:

http://localhost:8000/mcp

Supported MCP HTTP variables:

Variable	Default	Description
MCP_TRANSPORT	stdio	stdio, streamable-http, or sse
MCP_HOST	0.0.0.0	Bind host for HTTP transports
MCP_PORT	8000	Bind port; hosting-platform PORT takes precedence
MCP_PATH	/mcp	Streamable HTTP endpoint path
MCP_STATELESS_HTTP	true	Stateless behaviour for legacy HTTP clients
MCP_JSON_RESPONSE	false	JSON responses instead of SSE where supported
MCP_ALLOWED_HOSTS	empty	Comma-separated Host allowlist
MCP_ALLOWED_ORIGINS	empty	Comma-separated Origin allowlist
MCP_TRUST_PROXY	false	Disable SDK DNS-rebinding checks only behind a trusted proxy/tunnel

Docker with rotating VLESS egress

Start the complete stack:

docker compose up --build -d

Watch route selection and Xray health:

docker compose logs -f wb-analyzer-mcp

The MCP endpoint remains:

http://localhost:8000/mcp

The SOCKS ports 1080 and 1081 are bound only to 127.0.0.1 inside the container and are not published to the host.

Xray environment variables

Variable	Default	Description
XRAY_ENABLED	false	Enable the bundled rotator; deployment configs set it to true
OUTBOUND_PROXY	empty	HTTPX proxy URL; use socks5://127.0.0.1:1080 with the rotator
XRAY_SUBSCRIPTION_URL	configured public feed	Text subscription containing vless:// links
XRAY_SOCKS_PORT	1080	Active local SOCKS listener
XRAY_TEST_SOCKS_PORT	1081	Temporary validation listener
XRAY_VALIDATION_URL	https://www.wildberries.ru/	URL used for the real through-proxy probe
XRAY_VALIDATE_STATUS_MAX	399	Highest accepted HTTP status
XRAY_MAX_CANDIDATES	15	Maximum candidates tested per rotation attempt
XRAY_PROBE_TIMEOUT	12	Probe timeout in seconds
XRAY_ROTATE_INTERVAL	900	Periodic rotation interval in seconds
XRAY_HEALTH_INTERVAL	60	Active-route health-check interval
XRAY_HEALTH_FAILURES	2	Consecutive failures before forced rotation
XRAY_FEED_REFRESH_INTERVAL	7200	Subscription refresh interval
XRAY_STARTUP_TIMEOUT	180	Maximum time the supervisor waits for the first valid route
XRAY_IP_CHECK_URL	empty	Optional endpoint used only to log the selected public egress IP

Emergency bypass

To start the same image without Xray:

docker run --rm \
  -e XRAY_ENABLED=false \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_TRUST_PROXY=true \
  -p 8000:8000 \
  wildberries-tools-mcp

Render deployment

The repository contains render.yaml for a one-service Docker deployment. The Xray process and rotator run inside the same container as the MCP server, so no private sidecar service is required.

Create a Render Blueprint from this repository. After deployment, the endpoint will look like:

https://<service-name>.onrender.com/mcp

The Blueprint enables VLESS routing and waits for CI checks before automatic deployment.

For a custom subscription, override this environment variable in Render:

XRAY_SUBSCRIPTION_URL=https://example.com/my-vless-subscription.txt

Public deployment security

For a direct deployment on a stable hostname, prefer an explicit allowlist:

MCP_TRANSPORT=streamable-http \
MCP_ALLOWED_HOSTS='mcp.example.com,mcp.example.com:*' \
python server.py

When the MCP server is behind a trusted reverse proxy or hosting edge that validates the Host header, set:

MCP_TRUST_PROXY=true

Do not broadly expose an unauthenticated MCP endpoint without rate limiting or other access controls. The tool is read-only, but an open endpoint can still be abused for compute and outbound traffic.

Public VLESS nodes are also third-party infrastructure. Treat them as untrusted network transit. Do not route credentials, private APIs, or other sensitive application traffic through this mechanism. This project sends only the Wildberries retrieval requests through OUTBOUND_PROXY.

ChatGPT connection

1. Deploy the server so that /mcp is reachable over HTTPS.
2. Open ChatGPT developer/custom app settings.
3. Add the remote MCP endpoint, for example https://mcp.example.com/mcp.
4. Let the client discover the server tools.
5. Ask ChatGPT to analyse a Wildberries product URL or SKU.

Example prompt:

Проанализируй отзывы на этот товар и выдели основные плюсы, минусы и повторяющиеся проблемы: 12345678

The client can call get_wb_reviews and use the returned review texts for analysis.

CI validation

GitHub Actions performs two independent checks:

1. Builds the Docker image and runs representative Reality/TCP, WS/TLS, and XHTTP/TLS share links through xray run -test.
2. Starts the MCP container with XRAY_ENABLED=false, performs a real MCP initialize handshake, and verifies that tools/list advertises get_wb_reviews.

The CI path intentionally does not depend on the availability of third-party public VLESS nodes.

SSE compatibility mode

MCP_TRANSPORT=sse \
MCP_HOST=0.0.0.0 \
MCP_PORT=8000 \
MCP_SSE_PATH=/sse \
MCP_MESSAGE_PATH=/messages/ \
python server.py

License

MIT