Amazon Seller Operations MCP

Core Problem

Amazon sellers need same-day responses to listing suppression, account health, inventory, fees, and PPC issues.

What This Server Provides

This folder contains a production-minded MCP server scaffold with typed JSON tool responses, connector health metadata, OAuth-oriented configuration, rate-limit guards, stable error envelopes, and deterministic demo data until live vendor integrations are attached.

This server has received a production pass. It now includes local Amazon seller operations models for account health, listing suppression, FBA inventory health, fee and margin breakdowns, review sentiment, PPC recommendations, and appeal drafts.

Connectors

• Amazon SP Listings API via OAuth scope listings.read; env prefix AMAZON_LISTINGS
• Amazon SP Catalog API via OAuth scope catalog.read; env prefix AMAZON_CATALOG
• Amazon SP FBA Inventory API via OAuth scope inventory.read; env prefix AMAZON_FBA
• Amazon Ads API via OAuth scope advertising::campaign_management; env prefix AMAZON_ADS
• Amazon SP Orders API via OAuth scope orders.read; env prefix AMAZON_ORDERS
• Amazon SP Account Health API via OAuth scope account_health.read; env prefix AMAZON_HEALTH

MCP Tools

• get_account_health - ODR, cancellation, late shipment, and policy health.
• get_suppressed_listings - Suppressed listings with reasons and fix steps.
• get_inventory_health - FBA stock, reorder points, stranded inventory, fees.
• get_fee_breakdown - FBA/referral/storage fee breakdown and true margin.
• get_review_sentiment - Review themes and complaint velocity.
• get_ppc_recommendations - Bid, budget, negative keyword recommendations.
• draft_appeal - Amazon-formatted appeal draft.

Current Local Capabilities

• Surfaces account-health breaches, watch metrics, and policy warnings.
• Lists suppressed/inactive listings with fix steps and estimated daily revenue loss.
• Reports FBA available, reserved, inbound, stranded units, days of stock, and storage fees.
• Calculates true contribution margin after COGS, referral, FBA, storage, ads, and refund reserve.
• Summarizes review sentiment, negative themes, and complaint velocity by ASIN.
• Recommends PPC bid and negative keyword changes for review.
• Drafts Amazon-style appeal plans for human review; it does not submit appeals automatically.

Test

python -m pytest .\tests -q -p no:cacheprovider

Partial Platform Support

Customers only need to connect the Amazon surfaces they actually use. Missing Listings, Catalog, FBA, Orders, Account Health, or Amazon Ads credentials do not prevent the server from starting or running local intelligence tools.

Use get_live_connector_status to see configured connectors. Use test_amazon_sp_connection and test_amazon_ads_connection for read-only live smoke checks when those surfaces are connected.

Running Locally

powershell python -m venv .venv .\.venv\Scripts\pip install -e . .\.venv\Scripts\python -m amazon_seller_operations_mcp.server

Claude Desktop Config

json { "mcpServers": { "amazon-seller-operations": { "command": "python", "args": ["-m", "amazon_seller_operations_mcp.server"], "cwd": "D:\CUSTOMS\EARNALL\MCP Servers\05-amazon-seller-operations" } } }

Production Checklist

• Create OAuth 2.1 apps for each connector and set *_CLIENT_ID plus *_CLIENT_SECRET.
• Store refresh tokens in a secrets manager, never in repo files.
• Replace deterministic demo rows in server.py with API adapter calls.
• Persist raw snapshots and normalized warehouse tables for trend analysis.
• Add integration tests with recorded fixtures for every connector.
• Validate every tool in MCP Inspector before publishing.
• Deploy with a /health route through FastMCP streamable HTTP on Railway or Render.