amazon-ads-py¶
A typed Python client, command line tool (adsctl) and MCP server for the Amazon Ads API.
from amazon_ads import AmazonAds
ads = AmazonAds.from_env(env_file=".env")
us = ads.profile("US")
for kw in us.sp.keywords.list(states=["ENABLED"]):
print(kw.keyword_text, kw.match_type, kw.bid)
What it gives you¶
| Coverage | All 1,094 operations in Amazon's 202 published Ads API specs, callable by id (any endpoint, coverage) |
| Typed layer | Sponsored Products campaigns, ad groups, keywords, targets, negatives, product ads, portfolios; Sponsored Brands campaigns, keywords, negative keywords; suggested bids; change history; reports; profiles |
| Writes | Per-item results for Amazon's 207 responses, automatic chunking to batch limits, read-only fields stripped from updates (campaign management) |
| Plans | Before/after review, fingerprints, drift checks, rollback plans, restore-from-history (change plans) |
| Throttling | Retry-After honored, shared cooldown, no blind retries of writes (errors and throttling) |
| Reports | One call from request to rows, 31-day chunking, verified presets (reports) |
| Warehouse | SQLite history that outlives Amazon's retention and tracks restatements (warehouse) |
| CLI | adsctl for every read, plans for every write (CLI) |
| MCP | Claude reads freely, and writes only plans a person approved (MCP server) |
Where to start¶
- Getting started: get API access and credentials, make a first call.
- Campaign management for everyday reads and writes.
- API quirks: what the live API does that its docs do not say.
Design choices¶
- Policy free. The library moves data and makes writes safe. It has no opinion on what a bid should be.
- Amazon's names. Models accept and emit Amazon's camelCase field names as well as Python's snake_case, so the API docs apply unchanged.
- Unknown fields survive. Models keep fields Amazon adds before the library knows about them.
- Sync, thread-safe. One client can be shared between threads; token refresh and throttling cooldowns are shared.