# Amazon POE MCP Server

MCP server that extracts data from Amazon's **Product Opportunity Explorer** (Seller Central) via browser automation. POE data is not available through the Selling Partner API — this tool automates the UI directly.

## How it works

```
Claude Code / MCP Client
    │ (stdio)
    ▼
MCP Server (FastMCP)
    │ (Playwright CDP)
    ▼
Chrome Browser (with active Seller Central session)
    │
    ▼
Amazon Product Opportunity Explorer
```

The server connects to an already-open Chrome browser via Chrome DevTools Protocol (CDP), navigates the POE interface, and extracts data — either via Amazon's Download button or by scraping HTML tables.

## Setup

### 1. Install dependencies

```bash
cd amazon-poe-mcp
uv sync
uv run playwright install chromium
```

### 2. Launch Chrome with remote debugging

**Important:** You must kill ALL Chrome instances first, then relaunch. If Chrome is already running, the debug flag is silently ignored.

```bash
# Kill existing Chrome
pkill -9 -f "Google Chrome"
sleep 2

# Launch with CDP enabled (temp profile)
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir=/tmp/chrome-debug-profile
```

### 3. Log into Seller Central

Navigate to [sellercentral.amazon.es](https://sellercentral.amazon.es) (or your marketplace) in the Chrome window that just opened and log in manually.

### 4. Configure Claude Code

The project includes a `.mcp.json` file. When you open a Claude Code session from this directory, the `amazon-poe` tools will be available automatically.

If you need to create it manually:

```json
{
  "mcpServers": {
    "amazon-poe": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/arnauaumedes/Code/amazon-poe-mcp",
        "run",
        "src/amazon_poe_mcp/server.py"
      ]
    }
  }
}
```

## Quick start: example extraction

### 1. Launch Chrome with CDP

```bash
cd ~/Code/amazon-poe-mcp
./start-chrome.sh
```

Chrome opens. Navigate to `sellercentral.amazon.es` and log in.

### 2. Open Claude Code from the project

```bash
cd ~/Code/amazon-poe-mcp
claude
```

Claude Code detects `.mcp.json` and loads the 7 `amazon-poe` tools automatically.

### 3. Ask for what you need in natural language

**Search niches:**
> "Busca niches de 'magnesio' en el POE de España"

Claude calls `search_niche(keyword="magnesio")` and returns a table with ~25 niches, volumes, prices, growth, etc.

**Export data from a specific niche:**
> "Exporta los search terms y productos del niche 'magnesium glycinate'"

Claude uses the niche URL (from the previous step) and calls `export_search_terms` + `export_products`. CSVs appear in `output/`.

**Export everything at once:**
> "Exporta todos los datos del niche de magnesium glycinate"

Claude calls `export_all` — downloads search terms, products, customer reviews, returns and insights in one go.

### 4. Collect the CSVs

```
output/
├── magnesium_glycinate_search_terms_2026-03-02.csv
├── magnesium_glycinate_products_2026-03-02.csv
├── magnesium_glycinate_customer_reviews_2026-03-02.csv
└── magnesium_glycinate_returns_2026-03-02.csv
```

### Visual flow

```
You: ./start-chrome.sh → log into Seller Central
      │
You: claude (from ~/Code/amazon-poe-mcp)
      │
You: "busca niches de creatina"
      │
Claude: calls search_niche("creatina") → shows niche table
      │
You: "exporta todo del primer niche"
      │
Claude: calls export_all(niche_url) → 4 CSVs in output/
      │
You: open CSVs in Excel / analyze with Claude
```

You talk in natural language, Claude decides which tool to call, and the browser moves on its own in the background.

---

## MCP Tools

| Tool | Description | Output |
|------|-------------|--------|
| `search_niche(keyword, marketplace?)` | Search POE for a keyword, returns matching niches with metrics | JSON |
| `export_search_terms(niche_url, output_filename?)` | Export "Search terms" tab | CSV |
| `export_products(niche_url, output_filename?)` | Export "Products" tab | CSV |
| `export_customer_reviews(niche_url, output_filename?)` | Export "Customer Review Insights" tab | CSV |
| `export_returns(niche_url, output_filename?)` | Export "Returns" tab | CSV |
| `export_insights_and_trends(niche_url)` | Extract "Insights and trends" summary | JSON |
| `export_all(niche_url, prefix?)` | Export all tabs in one call | JSON + CSVs |

### Typical workflow

1. `search_niche("magnesio")` → get list of niches with URLs
2. Pick a niche URL from results
3. `export_all(niche_url, prefix="magnesio_glicinato")` → exports all tabs to `output/`

## Output

CSV files are saved to `./output/` with the naming convention:

```
{keyword}_{tab_name}_{YYYY-MM-DD}.csv
```

Example: `magnesium_glycinate_search_terms_2026-03-02.csv`

## Supported marketplaces

| Marketplace | Base URL |
|-------------|----------|
| Spain (default) | `sellercentral.amazon.es` |
| United States | `sellercentral.amazon.com` |

## Testing

```bash
# Unit tests
uv run pytest tests/ -v

# Manual integration test (requires Chrome + Seller Central session)
uv run python -c "
import asyncio
from amazon_poe_mcp.browser import BrowserManager
from amazon_poe_mcp.scraper import search_niche_in_poe

async def test():
    mgr = BrowserManager()
    await mgr.connect()
    page = await mgr.get_page()
    niches = await search_niche_in_poe(page, 'magnesio', 'Spain')
    print(f'Found {len(niches)} niches')
    for n in niches[:3]:
        print(f'  {n.niche_name} | vol:{n.search_volume}')
    await page.close()
    await mgr.disconnect()

asyncio.run(test())
"
```

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `ConnectionError: Could not connect to Chrome` | Chrome not running with `--remote-debugging-port=9222`. Kill all instances and relaunch. |
| CDP port not binding | Chrome was already running when you added the flag. Must kill ALL instances first (`pkill -9 -f "Google Chrome"`). |
| `PermissionError: not logged in` | Navigate to Seller Central in the debug Chrome and log in manually. |
| Selectors not finding elements | Amazon updates their UI periodically. Check `scraper.py` selectors against current POE HTML. |
| Download button fails | Falls back to HTML table scraping automatically. |

## Project structure

```
amazon-poe-mcp/
├── pyproject.toml
├── .mcp.json                      # Claude Code MCP config
├── src/amazon_poe_mcp/
│   ├── server.py                  # MCP tool definitions (FastMCP)
│   ├── browser.py                 # Chrome CDP connection manager
│   ├── scraper.py                 # POE navigation + data extraction
│   └── models.py                  # Data models + marketplace constants
├── tests/
│   ├── test_models.py
│   ├── test_browser.py
│   └── test_scraper.py
└── output/                        # Exported CSVs
```