# Wildberries MCP 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:**
   ```bash
   git clone <repository-url>
   cd wb-mcp-server
   ```

2. **Install dependencies:**
   ```bash
   pip install -e .
   ```

3. **Configure your API keys:**
   ```bash
   cp config.example.yaml config.yaml
   ```

   Edit `config.yaml` and add your Wildberries API keys:
   ```yaml
   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](https://seller.wildberries.ru)
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

```bash
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):

```json
{
  "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:**
```json
{
  "name": "get_wb_cards"
}
```

**Get cards from specific cabinet:**
```json
{
  "name": "get_wb_cards",
  "arguments": {
    "cabinet_name": "wb_cabinet1"
  }
}
```

**Get only cards with photos:**
```json
{
  "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:
```bash
pip install -e ".[dev]"
```

### Run tests:
```bash
pytest
```

### Code formatting:
```bash
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.