Wildberries Server

MCP (Model Context Protocol) server for Wildberries API that provides tools to interact with Wildberries marketplace data.

Features

• Multi-cabinet support: Configure multiple Wildberries cabinets (accounts) with separate API keys
• Automatic pagination: Handles pagination automatically to retrieve all data
• Retry logic: Built-in retry mechanism with exponential backoff for transient failures
• Rate limiting: Respects Wildberries API rate limits with automatic retry

Currently Available Tools

get_wb_cards

Get product cards (карточки товаров) from Wildberries.

Parameters:

• cabinet_name (optional): Name of the cabinet to fetch cards from. If not specified, fetches from all enabled cabinets.
• with_photo (optional): Filter cards by photo presence
  • -1 (default): all cards
  • 0: cards without photos
  • 1: cards with photos only

Returns: JSON with product cards including IDs, names, sizes, characteristics, photos, and metadata.

Installation

1. Clone the repository:

   git clone <repository-url>
   cd wb-mcp-server
   

2. Install dependencies:

   pip install -e .
   

3. Configure your API keys:

   cp config.example.yaml config.yaml
   

   Edit config.yaml and add your Wildberries API keys:

   cabinets:
     wb_cabinet1:
       api_key: "your-api-key-here"
       enabled: true
   
     wb_cabinet2:
       api_key: "another-api-key"
       enabled: true
   

Getting Wildberries API Keys

1. Go to Wildberries Seller Portal
2. Navigate to Settings → API Access
3. Create a new API key with required permissions:
   • Content API (read) - for product cards
4. Copy the API key and add it to your config.yaml
5. Keep your API keys secure - never commit them to git

Usage

Running the Server

python -m wb_mcp_server.server

Using with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "wildberries": {
      "command": "python",
      "args": ["-m", "wb_mcp_server.server"],
      "cwd": "/path/to/wb-mcp-server"
    }
  }
}

Example Tool Calls

Get all cards from all cabinets:

{
  "name": "get_wb_cards"
}

Get cards from specific cabinet:

{
  "name": "get_wb_cards",
  "arguments": {
    "cabinet_name": "wb_cabinet1"
  }
}

Get only cards with photos:

{
  "name": "get_wb_cards",
  "arguments": {
    "with_photo": 1
  }
}

Project Structure

wb-mcp-server/
├── src/wb_mcp_server/
│   ├── __init__.py
│   ├── config.py          # Configuration loader
│   ├── base_client.py     # HTTP client with retry logic
│   ├── wb_api.py          # Wildberries API client
│   └── server.py          # MCP server implementation
├── config.example.yaml    # Example configuration
├── config.yaml           # Your configuration (gitignored)
├── pyproject.toml        # Project dependencies
└── README.md

Development

Install with dev dependencies:

pip install -e ".[dev]"

Run tests:

pytest

Code formatting:

ruff check .
ruff format .

Roadmap

The following tools are planned for future releases:

• get_wb_orders - Fetch orders
• get_wb_sales - Fetch sales data
• get_wb_warehouse_remains - Fetch warehouse stock
• get_wb_prices - Fetch pricing information
• get_wb_campaigns - Fetch advertising campaigns
• get_wb_fullstats - Fetch advertising statistics
• get_wb_finance - Fetch financial reports
• get_wb_tariffs - Fetch tariff information

Security

• Keep your config.yaml file secure and never commit it to version control
• The .gitignore file is configured to exclude config.yaml by default
• API keys are passed in Authorization headers and not logged

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.