Mcp Amazon Sp Api

mcp-amazon-sp-api

MCP server that exposes the Amazon Selling Partner API to Claude Desktop and any other client that speaks the Model Context Protocol.

It wraps the python-amazon-sp-api SDK and ships 55+ tools across 19 SP-API scopes — catalog, orders, listings, reports, inventory, pricing, A+ content, feeds, fulfillment, messaging and more — with automatic pagination, throttle-aware retry and multi-marketplace support.

> Status: production-ready, used daily against the live SP-API. ~400 unit and integration tests, ~95% coverage.

---

Features

• 55+ MCP tools covering 19 SP-API scopes (see [Tool catalogue](#tool-catalogue)).
• Multi-marketplace. Every tool accepts a marketplace parameter (ES, DE, FR, IT, GB, NL, BE, PL, SE, IE, US, AE, SA). When omitted, falls back to SP_API_MARKETPLACE from .env.
• Safe writes. Mutating tools require confirm=True; without it they return a detailed plan preview so the agent can show the user what would happen.
• Automatic pagination on inventory, listings, finances, orders and catalog endpoints.
• Throttle-aware retry with exponential backoff for all SP-API calls.
• Reports pipeline (create → poll → download → parse) for Brand Analytics, FBA reports and Sales & Traffic.
• Bulk updates via JSON_LISTINGS_FEED for price/inventory.
• Credential resolution order: environment variables → macOS Keychain → .env.

Requirements

• Python ≥ 3.12
• uv (recommended) or any PEP 517 installer
• Amazon SP-API developer credentials (LWA app + refresh token)

Installation

git clone https://github.com/christian-ramos/mcp-amazon-sp-api.git
cd mcp-amazon-sp-api
uv sync

uv sync will create .venv/ and install the runtime dependencies declared in pyproject.toml. For development extras (pytest, ruff):

uv sync --group dev

Configuration

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

SP_API_REFRESH_TOKEN=Atzr|...
LWA_APP_ID=amzn1.application-oa2-client...
LWA_CLIENT_SECRET=...
SP_API_SELLER_ID=...
SP_API_MARKETPLACE=ES

To obtain these:

1. In Seller Central, go to Apps & Services → Develop Apps.
2. Create (or open) your SP-API application and authorize it for your seller account.
3. Note the LWA client ID and LWA client secret.
4. Generate a refresh token by self-authorizing the app for your seller account.
5. Copy your Seller ID from Settings → Account Info → Your Merchant Token.

Storing credentials in macOS Keychain (optional)

If you prefer not to keep secrets on disk, store them in the Keychain — the server will pick them up automatically:

security add-generic-password -s mcp-amazon-sp-api -a SP_API_REFRESH_TOKEN -w 'Atzr|...'
security add-generic-password -s mcp-amazon-sp-api -a LWA_APP_ID -w 'amzn1.application-oa2-client...'
security add-generic-password -s mcp-amazon-sp-api -a LWA_CLIENT_SECRET -w '...'

Resolution order is: environment variables → Keychain → .env.

Running

As a Claude Desktop MCP server

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "amazon-sp-api": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/mcp-amazon-sp-api",
        "run", "mcp-amazon-sp-api"
      ]
    }
  }
}

Restart Claude Desktop. The 55+ tools will appear under the amazon-sp-api server.

Standalone (for debugging)

uv run mcp-amazon-sp-api

This speaks MCP over stdio; you will need an MCP client on the other end (the MCP Inspector is great for this).

Tool catalogue

Tools are grouped by scope. See src/mcp_amazon_sp_api/tool_docs.py for the full per-tool documentation that Claude reads at runtime via the tool-docs:// MCP resource.

| Scope | Tools | |---|---| | Catalog & Orders | list_products, get_product_details, get_orders, get_order_items | | Analytics | get_sales_summary, get_returns_summary, get_order_finances, estimate_fees, get_profitability_report, get_sales_rankings | | Listings | get_listing_content, list_my_listings, get_listing_issues, get_product_type_info, update_listing_attribute, update_listing_batch | | Reports infra | request_report, check_report, download_report | | Brand Analytics | get_search_terms, get_search_performance, get_market_basket, get_repeat_purchases | | FBA Reports | get_fba_inventory, get_fba_returns, get_fba_fees_report, get_restock_suggestions | | Sales & Traffic | get_sales_and_traffic | | Inventory (realtime) | get_inventory | | Pricing | get_competitive_pricing, get_competitor_offers | | A+ Content | list_aplus_content, get_aplus_content, get_aplus_asin_relations | | Pricing cross-marketplace | get_cross_marketplace_prices, update_marketplace_price, sync_marketplace_prices | | Competitor analysis | analyze_competitor_prices, compare_with_competitors | | Listings restrictions | check_listing_restrictions, check_expansion_eligibility | | Feeds | bulk_update_prices, check_feed | | Fulfillment inbound | list_fba_shipments, get_fba_shipment_items, get_inbound_guidance | | Messaging | get_messaging_options, send_buyer_message | | Solicitations | check_review_eligibility, request_review | | Invoices | get_invoices, download_invoice | | Sales API | get_order_metrics |

Development

uv sync --group dev          # install with dev deps
uv run pytest tests/unit     # unit tests (no SP-API credentials needed)
uv run pytest -m integration # integration tests (require live credentials)
uv run ruff check .          # lint

Project layout:

src/mcp_amazon_sp_api/
├── server.py          # FastMCP entry point — registers all tool packages
├── config.py          # Credentials resolution and marketplace map
├── sp_client.py       # Re-export of clients/
├── clients/           # One module per SP-API scope (BaseClient + mixins)
├── tools/             # MCP tool implementations, grouped by scope
└── tool_docs.py       # Per-tool detailed docs exposed via tool-docs:// resource

See [ROADMAP.md](ROADMAP.md) for the implementation history and per-phase scope.

Security notes

• This server holds production seller credentials with full SP-API access. Treat .env like a password file — never commit it.
• Write tools (update_listing_attribute, update_listing_batch, update_marketplace_price, sync_marketplace_prices, bulk_update_prices, send_buyer_message, request_review) require confirm=True. Without confirmation they return a plan preview rather than executing.
• All requests honour SP-API rate limits via throttle-aware retry.

Disclaimer

This project is not affiliated with, endorsed by, or supported by Amazon.com, Inc. Trademarks belong to their respective owners.

License

[MIT](LICENSE) © Christian Ramos

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: christian-ramos
• Source: christian-ramos/mcp-amazon-sp-api
• License: MIT

Install and usage instructions live in the source repository linked above.