Skip to main content
Glama

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).

  • 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.

Related MCP server: shopline-mcp

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 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 © Christian Ramos

Available Tools

53 tools
analyze_competitor_pricesC

Buscar competidores y comparar precios y rankings.

Inputs: keywords (required), marketplace, max_results. Returns: result

bulk_update_pricesC

Actualizar precios en bulk vía feed. Requiere confirm=True.

Inputs: updates (required), confirm, marketplace. Returns: result

check_expansion_eligibilityC

Elegibilidad para vender en otros marketplaces EU.

Inputs: asin (required), marketplaces (required). Returns: result

check_feedC

Estado y resultado de un feed de actualización masiva.

Inputs: feed_id (required), marketplace. Returns: result

check_listing_restrictionsC

Ver restricciones para vender un ASIN.

Inputs: asin (required), condition, marketplace. Returns: result

check_reportB

Estado de un informe: IN_QUEUE, IN_PROGRESS, DONE, FATAL.

Inputs: report_id (required), marketplace. Returns: result

check_review_eligibilityC

Ver si puedes solicitar review para un pedido.

Inputs: order_id (required), marketplace. Returns: result

compare_with_competitorsC

Comparar tu producto vs competidores similares.

Inputs: my_asin (required), keywords (required), marketplace, max_results. Returns: result

download_invoiceC

Descargar documento de factura.

Inputs: invoice_id (required), marketplace. Returns: result

download_reportC

Descargar contenido de un informe completado.

Inputs: report_id (required), marketplace. Returns: result

estimate_feesC

Estimar fees de Amazon para un producto y precio.

Inputs: asin (required), price (required), is_fba, marketplace. Returns: result

get_aplus_asin_relationsC

ASINs asociados a un documento A+ Content.

Inputs: content_key (required), marketplace. Returns: result

get_aplus_contentC

Detalle de un documento A+ Content.

Inputs: content_key (required), marketplace. Returns: result

get_competitive_pricingC

Precios competitivos, Buy Box y rankings por ASIN.

Inputs: asins (required), marketplace. Returns: result

get_competitor_offersC

Ofertas de todos los vendedores para un ASIN.

Inputs: asin (required), marketplace. Returns: result

get_cross_marketplace_pricesC

Ver precio de un SKU en todos los marketplaces EU.

Inputs: sku (required), marketplaces. Returns: result

get_fba_fees_reportC

Tarifas de almacenamiento FBA actuales y largo plazo.

Inputs: marketplace. Returns: result

get_fba_inventoryC

Stock FBA por SKU vía report asíncrono.

Inputs: marketplace. Returns: result

get_fba_returnsC

Devoluciones FBA con motivo detallado vía report.

Inputs: days_back, marketplace. Returns: result

get_fba_shipment_itemsC

Items de un envío a FBA: enviado vs recibido.

Inputs: shipment_id (required), marketplace. Returns: result

get_inbound_guidanceC

Guía de envío a FBA: elegibilidad y prep requerido.

Inputs: asins (required), marketplace. Returns: result

get_inventoryC

Stock FBA en tiempo real por SKU.

Inputs: sku, marketplace. Returns: result

get_invoicesC

Obtener facturas por pedido o periodo.

Inputs: order_id, days_back, marketplace. Returns: result

get_listing_contentA

Contenido de tu listing: título, bullets, keywords, offers y atributos.

Busca primero en Listings API (datos del seller). Si faltan atributos, hace fallback a Catalog API (datos del catálogo, incluye traducciones BIL).

Inputs: sku (required), marketplace. Returns: result

get_listing_issuesD

Issues de calidad de un listing.

Inputs: sku (required), marketplace. Returns: result

get_market_basketC

Productos comprados junto con los tuyos (Brand Analytics).

Inputs: days_back, marketplace. Returns: result

get_messaging_optionsC

Tipos de mensaje disponibles para un pedido.

Inputs: order_id (required), marketplace. Returns: result

get_order_financesC

Desglose financiero de un pedido: fees, neto, margen.

Inputs: order_id (required), marketplace. Returns: result

get_order_itemsC

Items de un pedido: SKU, ASIN, precio, cantidad.

Inputs: order_id (required), marketplace. Returns: result

get_order_metricsC

Métricas de ventas agregadas. Respuesta inmediata.

Inputs: days_back, granularity, marketplace. Returns: result

get_ordersC

Pedidos recientes por fecha y estado.

Inputs: status, days_back, marketplace. Returns: result

get_product_detailsC

Detalle de un producto: título, marca, imágenes, rankings.

Inputs: asin (required), marketplace. Returns: result

get_product_type_infoC

Atributos válidos de un product type o buscar tipos.

Inputs: keywords, marketplace, product_type. Returns: result

get_profitability_reportC

Rentabilidad por SKU: ingresos, fees, margen neto.

Inputs: days_back, max_orders, marketplace. Returns: result

get_repeat_purchasesC

Tasa de recompra por ASIN (Brand Analytics).

Inputs: days_back, marketplace. Returns: result

get_restock_suggestionsC

Recomendaciones de restock: qué y cuánto reabastecer.

Inputs: marketplace. Returns: result

get_returns_summaryC

Resumen de devoluciones y reembolsos.

Inputs: days_back, marketplace. Returns: result

get_sales_and_trafficC

Sesiones, conversión, Buy Box % por ASIN vía report.

Inputs: days_back, marketplace. Returns: result

get_sales_rankingsC

Rankings de ventas (BSR) por categoría.

Inputs: asin (required), marketplace. Returns: result

get_sales_summaryC

Resumen de ventas: revenue, unidades, top productos.

Inputs: days_back, marketplace. Returns: result

get_search_performanceC

Rendimiento de tus ASINs en búsquedas (Brand Analytics).

Inputs: asins (required), marketplace. Returns: result

get_search_termsC

Top keywords con click/conversion share (Brand Analytics).

Inputs: days_back, marketplace. Returns: result

list_aplus_contentC

Listar documentos A+ Content de tu cuenta.

Inputs: marketplace. Returns: result

list_fba_shipmentsC

Envíos a FBA y su estado.

Inputs: status, marketplace, shipment_ids. Returns: result

list_my_listingsC

Listar todos tus listings con estado e issues.

Inputs: status, page_size, marketplace, issue_severity. Returns: result

list_productsC

Buscar productos en el catálogo de Amazon por keywords.

Inputs: keywords, marketplace. Returns: result

request_reportC

Solicitar generación de un informe de Amazon (asíncrono).

Inputs: report_type (required), days_back, marketplace. Returns: result

request_reviewC

Solicitar review al comprador. Requiere confirm=True.

Inputs: order_id (required), confirm, marketplace. Returns: result

send_buyer_messageC

Enviar mensaje al comprador. Requiere confirm=True.

Inputs: body (required), order_id (required), message_type (required), confirm, +1 more. Returns: result

sync_marketplace_pricesC

Sincronizar precios a varios marketplaces. Requiere confirm=True.

Inputs: sku (required), targets (required), base_price (required), product_type (required), +3 more. Returns: result

update_listing_attributeC

Actualizar un atributo de un listing. Requiere confirm=True.

Inputs: sku (required), value (required), product_type (required), attribute_name (required), +3 more. Returns: result

update_listing_batchC

Actualizar múltiples atributos de un listing. Requiere confirm=True.

Inputs: sku (required), updates (required), product_type (required), confirm, +1 more. Returns: result

update_marketplace_priceC

Cambiar precio en un marketplace. Requiere confirm=True.

Inputs: sku (required), price (required), marketplace (required), product_type (required), +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.4/5.0

    Scored across 53 tools

    Disambiguation2/5

    There is significant overlap among tools related to pricing and competition (e.g., analyze_competitor_prices, compare_with_competitors, get_competitive_pricing, get_competitor_offers) and among inventory reporting tools (get_fba_inventory, get_inventory, get_fba_fees_report, get_profitability_report). This ambiguity would likely cause an agent to select the wrong tool.

    Naming Consistency4/5

    Tool names consistently follow verb_noun pattern (get_, list_, update_, check_, request_), with no mixing of casing styles. A few prefixes (check_, request_) deviate from the majority get_/list_/update_, but the pattern remains predictable overall.

    Tool Count2/5

    With 53 tools, the server is overly large for typical MCP usage. While it covers a broad domain (Amazon SP API), the high count increases cognitive load and makes it harder for agents to navigate. A more focused subset would improve coherence.

    Completeness3/5

    The tool set covers many essential areas (orders, inventory, listings, reports, A+ content, fees), but notable gaps exist: no tool for creating listings (only updating), no advertising management, and no returns processing beyond reporting. This leaves some workflows incomplete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for the Shopline Open API. Exposes 140+ tools for querying and managing orders, products, customers, promotions, analytics, and store settings from your Shopline store via Claude.
      100
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      An MCP server that exposes marketplace seller operations (Shopee first) as tools Claude can call, enabling automation of product, pricing, inventory, customer service, and other seller tasks.
      32
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Amazon Selling Partner API and Advertising API, enabling access to orders, inventory, pricing, ads, and reports via natural language.
      1
      MIT