Amazon SP-API MCP Server

A Model Context Protocol (MCP) server that connects Claude to Amazon Seller Central via the SP-API. Enables natural language queries for sales data, inventory, reports, fees, reimbursements, and analytics.

Security Notice (March 31, 2026): The axios npm package was briefly compromised in a supply chain attack. Malicious versions 1.14.1 and 0.30.4 were published between 00:21 and 03:15 UTC on March 31 before npm removed them. These versions contained a trojanized dependency (plain-crypto-js) that installed a remote access trojan. This repo's axios dependency has been pinned to 1.14.0 (the last clean version). If you ran npm install during the attack window, delete your node_modules folder and reinstall. See: Snyk advisory, Datadog analysis.

Key Feature: No AWS Credentials Required

As of October 2023, Amazon SP-API no longer requires AWS IAM credentials. This server uses LWA (Login with Amazon) OAuth 2.0 only, making setup simpler and more secure.

Features

Core Operations

• Orders: Get orders, order details, and order items
• Inventory: FBA inventory summary and detailed health metrics
• Sales: Sales metrics by day/week/month with totals and averages

Financial Reports

• Reimbursements: FBA reimbursements for lost/damaged inventory
• Settlements: Payment disbursement details and breakdowns
• Fee Estimates: Per-SKU FBA fee estimates
• Storage Fees: Monthly storage charges
• Long-term Storage Fees: LTSF for aged inventory

Analytics

• Sales & Traffic: Sessions, page views, conversion rates, buy box %
• Search Terms: Brand Analytics search term performance (requires Brand Registry)
• Inventory Ledger: Track inventory movements and adjustments

Prerequisites

• Node.js 18+
• Amazon Seller Central account
• SP-API application registered in Developer Central
• LWA credentials (Client ID, Client Secret, Refresh Token)

Installation

git clone https://github.com/mansournorouzi/amazon-sp-mcp.git
cd amazon-sp-mcp
npm install
npm run build

Configuration

Create a .env file with your credentials:

# Copy the example
cp .env.example .env

Required environment variables:

# Login with Amazon (LWA) OAuth 2.0 Credentials
LWA_CLIENT_ID=amzn1.application-oa2-client.xxxxx
LWA_CLIENT_SECRET=your_lwa_client_secret
LWA_REFRESH_TOKEN=Atzr|your_refresh_token

# Seller Information
SELLER_ID=your_seller_id
MARKETPLACE_ID=ATVPDKIKX0DER

# SP-API Endpoint (optional, defaults to North America)
SP_API_ENDPOINT=https://sellingpartnerapi-na.amazon.com

Marketplace IDs

| Region | Marketplace | ID | |--------|------------|-----| | US | Amazon.com | ATVPDKIKX0DER | | CA | Amazon.ca | A2EUQ1WTGCTBG2 | | MX | Amazon.com.mx | A1AM78C64UM0Y8 | | UK | Amazon.co.uk | A1F83G8C2ARO7P | | DE | Amazon.de | A1PA6795UKMFR9 | | JP | Amazon.co.jp | A1VC38T7YXB528 |

SP-API Endpoints

| Region | Endpoint | |--------|----------| | North America | https://sellingpartnerapi-na.amazon.com | | Europe | https://sellingpartnerapi-eu.amazon.com | | Far East | https://sellingpartnerapi-fe.amazon.com |

Usage with Claude Desktop

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

{
  "mcpServers": {
    "amazon-seller": {
      "command": "node",
      "args": ["/path/to/amazon-sp-mcp/build/index.js"],
      "env": {
        "LWA_CLIENT_ID": "amzn1.application-oa2-client.xxxxx",
        "LWA_CLIENT_SECRET": "your_secret",
        "LWA_REFRESH_TOKEN": "Atzr|your_token",
        "SELLER_ID": "your_seller_id",
        "MARKETPLACE_ID": "ATVPDKIKX0DER",
        "SP_API_ENDPOINT": "https://sellingpartnerapi-na.amazon.com"
      }
    }
  }
}

Restart Claude Desktop after making changes.

Usage with Claude Code

Add .mcp.json to your project root:

{
  "mcpServers": {
    "amazon-seller": {
      "command": "node",
      "args": ["./build/index.js"],
      "env": {
        "LWA_CLIENT_ID": "${LWA_CLIENT_ID}",
        "LWA_CLIENT_SECRET": "${LWA_CLIENT_SECRET}",
        "LWA_REFRESH_TOKEN": "${LWA_REFRESH_TOKEN}",
        "SELLER_ID": "${SELLER_ID}",
        "MARKETPLACE_ID": "${MARKETPLACE_ID}",
        "SP_API_ENDPOINT": "${SP_API_ENDPOINT}"
      }
    }
  }
}

Available Tools

Orders

| Tool | Description | |------|-------------| | get_orders | List orders by date range, status, fulfillment channel | | get_order_details | Get details for a specific order | | get_order_items | Get line items for an order |

Inventory

| Tool | Description | |------|-------------| | get_inventory_summary | FBA inventory levels and health | | get_fba_inventory_details | Detailed breakdown of reserved/unfulfillable quantities |

Sales

| Tool | Description | |------|-------------| | get_sales_metrics | Sales aggregates by day/week/month |

Financial Reports

| Tool | Description | |------|-------------| | get_fba_reimbursements | Lost/damaged inventory reimbursements | | get_settlement_report | Payment disbursement details | | get_fba_fee_estimates | Per-SKU fee breakdown | | get_storage_fees | Monthly storage charges | | get_longterm_storage_fees | LTSF for aged inventory (365+ days) |

Analytics

| Tool | Description | |------|-------------| | get_sales_traffic_report | Sessions, page views, conversion rates | | get_search_terms_report | Brand Analytics search terms (Brand Registry required) | | get_inventory_ledger | Inventory movement summary |

Example Queries

Once configured, you can ask Claude questions like:

• "What were my sales last week?"
• "Show me my FBA reimbursements for January"
• "What's my current inventory health?"
• "Pull my settlement report for the last payment"
• "What are my storage fees by SKU?"
• "Which products have the best conversion rate?"
• "Show me my long-term storage fees"

Development

# Build
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Format
npm run format

Architecture

src/
├── index.ts                    # MCP server entry point
├── config/
│   └── index.ts                # Configuration & validation
├── auth/
│   └── token-manager.ts        # LWA OAuth 2.0 token management
├── client/
│   ├── sp-api-client.ts        # HTTP client (no AWS signing!)
│   └── rate-limiter.ts         # SP-API rate limiting
├── tools/
│   ├── index.ts                # Tool registry
│   ├── orders.ts               # Orders API tools
│   ├── inventory.ts            # Inventory API tools
│   ├── sales.ts                # Sales API tools
│   └── reports/
│       ├── reimbursements.ts   # FBA reimbursements
│       ├── settlements.ts      # Settlement reports
│       ├── fees.ts             # Fee reports
│       └── analytics.ts        # Brand analytics
├── types/
│   └── sp-api.ts               # TypeScript definitions
└── utils/
    ├── csv-parser.ts           # Report CSV parsing
    └── report-poller.ts        # Async report polling

License

MIT

Resources

• Amazon SP-API Documentation
• SP-API Report Types
• MCP Protocol
• SP-API No Longer Requires AWS Credentials