# Amazon Seller MCP Server

MCP (Model Context Protocol) server exposing Amazon Selling Partner API tools for sellers. Built from the Swagger models in `../models/`.

## Tools (47)

Full coverage of every operation in the underlying API models per group.

| Group | Tools |
|---|---|
| **Orders** (Orders API v0 — all 10 ops) | `search_orders`, `get_order` (header+items), `get_order_items`, `get_order_buyer_info` †, `get_order_address` †, `get_order_items_buyer_info` †, `confirm_shipment`, `update_shipment_status` (in-store pickup), `get_order_regulated_info`, `update_verification_status` |
| **FBA / Inventory** (FBA Inventory + Inbound Eligibility) | `get_fba_inventory` (low-stock flagging), `check_fba_inbound_eligibility`, `create_sandbox_inventory_item` ‡, `delete_sandbox_inventory_item` ‡, `add_sandbox_inventory` ‡ |
| **Listings** (Listings Items 2021-08-01 — all 5 ops + Restrictions + Product Type Definitions) | `search_listings`, `get_listing`, `update_listing` (PATCH price/qty, validation preview), `create_or_replace_listing` (PUT), `delete_listing`, `get_listing_restrictions` (gating check), `search_product_types`, `get_product_type_definition` |
| **Catalog** (Catalog Items 2022-04-01) | `search_catalog`, `get_catalog_item` |
| **Pricing** (Product Pricing v0 — all 6 ops + 2022-05-01 + Product Fees — all 3 ops) | `get_pricing`, `get_competitive_pricing`, `get_item_offers`, `get_listing_offers`, `get_item_offers_batch`, `get_listing_offers_batch`, `get_featured_offer_expected_price` (buy box target price), `get_competitive_summary`, `estimate_fees`, `estimate_fees_batch` |
| **Analytics** (Sales + Finances v0 — all 4 ops) | `get_sales_metrics`, `list_financial_events` (date range or per order), `list_financial_event_groups` (settlements), `list_financial_events_by_group` |
| **Reports** (Reports 2021-06-30 — all 9 ops) | `create_report`, `get_report` (auto-download + gunzip), `list_reports`, `cancel_report`, `create_report_schedule`, `list_report_schedules`, `get_report_schedule`, `cancel_report_schedule` |

† Buyer PII — requires the restricted (PII) role on your SP-API app; the server creates the Restricted Data Token automatically via the Tokens API.
‡ Sandbox only — requires `SPAPI_SANDBOX=true`; used to seed FBA sandbox test data.

## Setup

```bash
cd mcp-server
npm install
npm run build
```

### Credentials

Self-authorize an SP-API app in Seller Central (Apps & Services → Develop Apps) to obtain LWA credentials and a refresh token. SP-API no longer requires AWS SigV4 — only the LWA token.

| Variable | Required | Description |
|---|---|---|
| `SPAPI_LWA_CLIENT_ID` | yes | LWA client ID of your SP-API app |
| `SPAPI_LWA_CLIENT_SECRET` | yes | LWA client secret |
| `SPAPI_REFRESH_TOKEN` | yes | Refresh token from the seller authorization |
| `SPAPI_REGION` | no | `na` (default), `eu`, or `fe` |
| `SPAPI_DEFAULT_MARKETPLACE` | no | Country code, default `US` |
| `SPAPI_SELLER_ID` | for listings | Merchant token (Settings → Account Info → Merchant Token) |
| `SPAPI_SANDBOX` | no | `true` to use the SP-API sandbox |

### Claude Desktop / Claude Code config

```json
{
  "mcpServers": {
    "amazon-seller": {
      "command": "node",
      "args": ["/path/to/selling-partner-api-models/mcp-server/dist/index.js"],
      "env": {
        "SPAPI_LWA_CLIENT_ID": "amzn1.application-oa2-client...",
        "SPAPI_LWA_CLIENT_SECRET": "...",
        "SPAPI_REFRESH_TOKEN": "Atzr|...",
        "SPAPI_REGION": "na",
        "SPAPI_DEFAULT_MARKETPLACE": "US",
        "SPAPI_SELLER_ID": "A1EXAMPLE"
      }
    }
  }
}
```

Or with Claude Code: `claude mcp add amazon-seller -e SPAPI_LWA_CLIENT_ID=... -e SPAPI_LWA_CLIENT_SECRET=... -e SPAPI_REFRESH_TOKEN=... -- node /path/to/mcp-server/dist/index.js`

## Notes

- Buyer PII tools (`get_order_buyer_info`, `get_order_address`, `get_order_items_buyer_info`) create a Restricted Data Token automatically (cached ~1h). A 403 means your SP-API app lacks the restricted role approval from Amazon.
- Responses are truncated at 25,000 characters with pagination hints; all tools support `nextToken`/`pageToken` where the API does.
- 429 throttling is retried automatically with exponential backoff (up to 3 retries).
- `update_listing` supports `validateOnly: true` (VALIDATION_PREVIEW) to dry-run a patch before applying.