wildberries_mcp

# Wildberries Analytics MCP Connects Wildberries analytics to Claude, Cursor, and other AI assistants. You can ask about sales, search queries, stock levels, and download reports. ## Quick Start (3 steps) **1. Install uv and dependencies** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh git clone https://github.com/dias-zhanabayev/wildberries_mcp cd wildberries_mcp uv sync ``` **2. Create `.env` with WB token** ```bash cp example.env .env # Open .env and insert token from seller's cabinet → Settings → API Access ``` **3. Connect to Cursor or Claude** Open MCP settings and add server (see [Integration](#integration)). ## What is it MCP (Model Context Protocol) is a way to give AI access to external data. This server connects **Wildberries analytics** to Claude Desktop and Cursor. **What can you do:** | Section | Examples | |--------|---------| | Sales funnel | Statistics by cards, period comparison | | Search | Positions in search results, top queries by product, orders from search | | Stock levels | By products, sizes, warehouses | | CSV reports | Create, check status, download | **API limitation:** 3 requests per minute. ## Installation ### Requirements - Python 3.12+ - [uv](https://astral.sh/uv/) — package manager (lightweight replacement for pip) ### Steps ```bash # 1. Install uv curl -LsSf https://astral.sh/uv/install.sh | sh # 2. Clone project git clone https://github.com/dias-zhanabayev/wildberries_mcp cd wildberries_mcp # 3. Install dependencies uv sync # 4. Configure token cp example.env .env # Insert WILDBERRIES_TOKEN in .env ``` ### Run ```bash uv run main.py ``` ## Integration The server works through Cursor or Claude Desktop. You need to specify how to run it. ### Cursor / Claude Desktop (without Docker) In MCP config (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json` or Cursor settings), add: ```json { "mcpServers": { "wildberries": { "command": "uv", "args": ["--directory", "/full/path/to/wildberries-mcp", "run", "main.py"], "env": { "WILDBERRIES_TOKEN": "your-wb-token" } } } } ``` Replace `/full/path/to/wildberries-mcp` and `your-wb-token`. ### Docker ```bash # Build docker compose build # Run (token taken from .env) cp example.env .env # Insert token in .env docker compose run --rm wildberries-mcp ``` **Option for Claude/Cursor via Docker:** ```json "wildberries": { "command": "docker", "args": ["compose", "-f", "/path/to/wildberries-mcp/docker-compose.yml", "run", "--rm", "-T", "wildberries-mcp"], "env": { "WILDBERRIES_TOKEN": "your-wb-token" } } ``` ## Query Examples After connecting, you can write in plain language: - Show sales statistics for the last week - What search queries lead to product card 123456? - Stock levels by warehouses for the current month - Create a CSV report on detailed history for June - Compare sales funnel for this month with last month - Top 20 queries that order product 789012 - Stock levels by sizes for product 456789 - Statuses and list of my reports ## Tools (Reference) Below is a list of all tools and their parameters. In normal usage, Claude will select the right one — no need to study. ### Sales Funnel | Tool | What it does | |------------|-----------| | `sales_funnel_products` | Card statistics for period (up to 365 days) | | `sales_funnel_products_history` | Daily/weekly statistics (max. 1 week) | | `sales_funnel_grouped_history` | Groups by subjects/brands/labels | ### Search Reports | Tool | What it does | |------------|-----------| | `search_report_main` | Positions, visibility, transitions | | `search_report_table_groups` | Pagination by groups | | `search_report_table_details` | Pagination by products in group | | `search_report_product_search_texts` | Top queries by product | | `search_report_product_orders` | Orders by product from search | ### Stock Levels | Tool | What it does | |------------|-----------| | `stocks_report_groups` | Stock levels by groups | | `stocks_report_products` | Stock levels by products | | `stocks_report_sizes` | Stock levels by sizes (requires article) | | `stocks_report_offices` | Stock levels by warehouses | ### CSV Reports | Tool | What it does | |------------|-----------| | `nm_report_create` | Create report task | | `nm_report_list` | List and statuses of reports | | `nm_report_retry` | Retry on failure | | `nm_report_download_file` | Download ZIP (available for 48 hours) | Parameter format — see [Wildberries API](https://dev.wildberries.ru/). ## Development ### Dev mode (MCP inspector) ```bash uv pip install "mcp[cli]" mcp dev wildberries_mcp.py ``` ### Environment Variables | Variable | Description | |------------|----------| | `WILDBERRIES_TOKEN` | WB token (required). Seller's cabinet → Settings → API Access | ## Errors - **No token** — check `WILDBERRIES_TOKEN` in `.env` or MCP config - **3 requests per minute** — API limit, make pauses between query series - **API 4xx/5xx** — error text comes in response - **Invalid JSON** — in arrays (`nm_ids`, `brand_names`, etc.) must be valid JSON, e.g., `[123, 456]`