# Lazada MCP

A read-only MCP server for Lazada Open Platform. It provides access to orders, transactions, fee breakdowns, and per-SKU profit analysis.

## Features

- Summarize sales, deductions, and net received amounts
- Retrieve transaction details from the Lazada Finance API
- Break down fees using the transaction types returned by Lazada
- Retrieve order and order-item details
- Calculate profit per SKU using seller-defined costs

Available MCP tools:

- `get_finance_summary`
- `get_transaction_details`
- `get_fee_breakdown`
- `get_order`
- `get_order_items`
- `get_order_finance`
- `get_order_profit`
- `list_orders`

## Requirements

- Python 3.14+
- A Lazada Open Platform app
- Lazada App Key and App Secret
- Seller Access Token
- An MCP-compatible client such as Codex

## Installation

```bash
git clone https://github.com/chanoktrue/lazada-mcp.git
cd lazada-mcp

python3.14 -m venv .venv
./.venv/bin/pip install -r requirements.txt
```

## Environment Configuration

Create a `.env` file. Never commit this file:

```env
URL_THAI=https://api.lazada.co.th/rest
LAZADA_APP_KEY=your_app_key
LAZADA_APP_SECRET=your_app_secret
ACCESS_TOKEN=your_access_token

LAZADA_FINANCE_API_PATH=/finance/transaction/details/get
LAZADA_FINANCE_PAGE_SIZE=100

# Product costs in Thai baht, keyed by seller SKU
LAZADA_SKU_COSTS_JSON={"SKU-001":{"unit_cost":120,"packaging_cost":5}}
```

Protect the environment file and verify that it is ignored by Git:

```bash
chmod 600 .env
git status --ignored
```

## Run as an stdio MCP Server

```bash
./.venv/bin/python lazada_mcp_server.py
```

Example Codex configuration:

```toml
[mcp_servers.lazada_finance]
command = "/absolute/path/lazada-mcp/.venv/bin/python"
args = ["/absolute/path/lazada-mcp/lazada_mcp_server.py"]
cwd = "/absolute/path/lazada-mcp"
```

Restart Codex or start a new session after changing the configuration.

## Usage Examples

Retrieve transaction details:

```text
get_transaction_details
start_date = "2026-07-01"
end_date = "2026-07-15"
```

View the fee breakdown for an order:

```text
get_fee_breakdown
start_date = "2026-07-01"
end_date = "2026-07-15"
order_id = "123456789"
```

Analyze order profitability:

```text
get_order_profit
order_id = "123456789"
start_date = "2026-07-01"
end_date = "2026-07-15"
```

## Profit Calculation

```text
Profit = sales price - discounts - Lazada fees - product cost - packaging cost
```

When Lazada reports a fee at order level instead of SKU level, the server allocates the fee based on each SKU's share of the order value. The response includes a warning indicating that the value is allocated rather than directly reported at SKU level.

## Security

- Never commit `.env`, access tokens, refresh tokens, or App Secrets
- Keep using the included `.gitignore`
- Use the MCP in read-only mode unless write operations are explicitly required
- Set `.env` permissions to `600`
- Rotate the Lazada App Secret and tokens immediately if they were ever exposed
- Do not expose this stdio server directly to the public internet

## License

Distributed under the MIT License. See [LICENSE](LICENSE) for details.