Metadata-Version: 2.4
Name: amazon-seller-operations-mcp
Version: 0.1.1
Summary: Amazon Seller Operations MCP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: license_status.py
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.7.0
Dynamic: license-file

# 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

```powershell
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.

<!-- mcp-name: io.github.atul0016/amazon-seller-operations -->
