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

Related MCP server: ya-reviews-mcp

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:

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

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