@codespar/mcp-amazon

@codespar/mcp-amazon

MCP server for the Amazon Selling Partner API (SP-API) — the biggest global marketplace, including Amazon BR, Amazon MX, Amazon US, and all EU/FE marketplaces.

For LatAm sellers, Amazon rounds out the marketplace trio already in this catalog:

• Mercado Libre (@codespar/mcp-mercadolibre) — dominant in LatAm generally (BR, AR, MX, CO, CL).
• Shopee (@codespar/mcp-shopee) — heavy in Brazil and rapidly growing regionally.
• Amazon (this package) — global reach, plus Amazon BR/MX for LatAm sellers and cross-border into Amazon US/EU/JP.

Together these three cover essentially every marketplace where a LatAm merchant transacts meaningful GMV.

Tools

Tool	Endpoint	Purpose
list_orders	GET /orders/v0/orders	List orders by marketplace, time window, status
get_order	GET /orders/v0/orders/{id}	One order
get_order_items	GET /orders/v0/orders/{id}/orderItems	Order line items (ASIN, SKU, qty, price)
get_listings_item	GET /listings/2021-08-01/items/{sellerId}/{sku}	Read a listing
put_listings_item	PUT /listings/2021-08-01/items/{sellerId}/{sku}	Create/replace a listing
delete_listings_item	DELETE /listings/2021-08-01/items/{sellerId}/{sku}	Delete a listing
search_catalog_items	GET /catalog/2022-04-01/items	Catalog reference search by identifier/keyword
get_inventory_summary	GET /fba/inventory/v1/summaries	FBA inventory (fulfillable, inbound, reserved)
create_report	POST /reports/2021-06-30/reports	Request an async report
get_report	GET /reports/2021-06-30/reports/{id}	Poll report status
list_financial_events	GET /finances/v0/financialEvents	Financial events for reconciliation
get_order_shipment_status	GET /shipping/v1/shipments/{id}	Shipment status (Amazon Shipping)
create_subscription	POST /notifications/v1/subscriptions/{type}	Event subscription (webhook-equivalent via SQS/EventBridge)

Install

npm install @codespar/mcp-amazon

Environment

AMAZON_LWA_CLIENT_ID="amzn1.application-oa2-client....."
AMAZON_LWA_CLIENT_SECRET="..."
AMAZON_REFRESH_TOKEN="Atzr|..."          # long-lived, seller-authorized
AMAZON_MARKETPLACE_ID="A2Q3Y263D00KWC"   # BR; ATVPDKIKX0DER=US, A1AM78C64UM0Y8=MX
AMAZON_REGION="na"                        # na | eu | fe (default na)
AMAZON_SELLER_ID="A3..."                  # optional; default for Listings tools

Marketplace ids (common)

Marketplace	Id	Region
Brazil	A2Q3Y263D00KWC	na
United States	ATVPDKIKX0DER	na
Mexico	A1AM78C64UM0Y8	na
Canada	A2EUQ1WTGCTBG2	na
Spain	A1RKKUPIHCS9HS	eu
United Kingdom	A1F83G8C2ARO7P	eu
Germany	A1PA6795UKMFR9	eu
Japan	A1VC38T7YXB528	fe

Authentication

SP-API uses a dual-step Login with Amazon (LWA) flow:

• Exchange refresh token → access token (1-hour lifetime). The server POSTs to https://api.amazon.com/auth/o2/token with grant_type=refresh_token and your client_id / client_secret / refresh_token. The result is cached in memory until ~1 minute before expiry.
• Call SP-API with the regional base URL and header x-amz-access-token: <token> plus Content-Type: application/json.

AWS Signature v4 request signing was the historical requirement for SP-API. Amazon removed the SigV4 requirement in 2023 for most tenants, so this server uses LWA-only auth. If your seller is still flagged as requiring SigV4, you will need to wrap amazonRequest with a signer (@aws-sdk/signature-v4) — not included here.

Regional base URLs

• NA (Americas, including BR/US/MX/CA): https://sellingpartnerapi-na.amazon.com
• EU (Europe + India + MENA): https://sellingpartnerapi-eu.amazon.com
• FE (Far East — Japan, Australia, Singapore): https://sellingpartnerapi-fe.amazon.com

Select with AMAZON_REGION. Brazil and the Americas use na.

Run

# stdio (default — Claude Desktop, Cursor, etc)
npx @codespar/mcp-amazon

# HTTP (server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-amazon

Notifications

create_subscription is webhook-equivalent for SP-API. Amazon does not push HTTP webhooks directly — instead, you create a destination (SQS queue or EventBridge bus) via POST /notifications/v1/destinations first, then attach subscriptions to that destination. This package covers subscription creation; destination provisioning is a one-time setup typically done via the AWS Console or a deploy script.

Status

0.1.0-alpha.1 — SP-API has 30+ product sections and this package covers the commerce-relevant subset (orders, listings, catalog, inventory, reports, finances, shipping, notifications). Endpoint paths and auth flow are implemented to the published spec; tool contracts should be integration-tested against real seller tokens before production use. The LWA refresh flow and x-amz-access-token header usage are confirmed against current SP-API docs.

License

MIT