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

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.

# 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 (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:

{
  "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

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

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

# 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