Amazon Ads Simulator MCP

A read-only MCP server for inspecting ad-bid recommendations and comparing explicit business assumptions. Eight tools connect a small TypeScript rules engine to an AI client. The default demo uses four fictional ad targets and needs no account, API key or database.

This portfolio edition contains a reproducible sample of the analysis workflow. It does not connect to Amazon Ads, change bids or demonstrate measured advertising gains.

Try it

Requires Node.js 22 or later and npm. CI verifies Node.js 24 LTS.

npm ci
npm run demo
npm test
npm run build
npm start

npm run demo prints a baseline and a conservative scenario using only in-memory fixtures. The server listens on http://127.0.0.1:3001; GET /health identifies the data source and POST /mcp accepts Streamable HTTP MCP requests. Configure an MCP client with that local endpoint.

Example prompts after connecting: “Explain the decrease recommendation for the fictional sample target” and “Compare the baseline with a 5% maximum increase and a 10% maximum decrease.”

Related MCP server: google-marketing-mcp

Tools

How the calculation works

Rows must meet minimum spend, click and impression thresholds. Eligible rows with no sales can receive a capped bid decrease; rows below or above the target advertising-cost-of-sales bands receive a capped increase or decrease. All other rows are held. Confidence labels reflect evidence-volume rules, not statistical confidence intervals.

Forecast spend and ad sales use user-controlled elasticity assumptions. A conversion-rate adjustment applies to every row, including held bids. A zero total-revenue denominator produces an unavailable ratio rather than infinity. The unused traffic-elasticity input from the earlier implementation is omitted.

The included backtest figures are synthetic. The service reads externally generated evaluation summaries; it is not a historical bid replay engine, a causal experiment or a trained sales predictor.

Structure

src/app.ts         MCP tools and HTTP application
src/engine.ts      Recommendation rules and scenario arithmetic
src/fixtures.ts    Fictional demonstration records
src/data.ts        Explicit sample, file and database sources
src/access.ts      Authentication boundary for configured data
src/db.ts          Optional PostgreSQL storage adapter
migrations/       Optional database schema
scripts/          Offline demo and explicit database utilities
test/             Rule, data-boundary and HTTP behavior tests

Optional local data and PostgreSQL

Sample mode is the default and ignores ambient DATABASE_URL and SIM_DATA_DIR settings. To use your own files, explicitly set SIM_DATA_SOURCE=files, SIM_DATA_DIR and a locally generated MCP_ACCESS_TOKEN of at least 32 characters. Files use the schemas in src/types.ts and the names bid_simulation_targeting_current_results.json and bid_simulation_backtest_results.json.

For PostgreSQL, set SIM_DATA_SOURCE=database, DATABASE_URL and the same token requirement. npm run db:migrate and npm run db:import are explicit database-write utilities; the HTTP MCP tools remain read-only. The import utility also requires SIM_DATA_DIR. These commands are not part of the demo or CI.

Send Authorization: Bearer <your locally generated token> for every HTTP request when a token is configured. Missing or short tokens prevent non-sample startup. TLS certificate verification is required for remote PostgreSQL; PGSSLMODE=disable is accepted only for loopback hosts. Use HTTPS in front of any remotely served authenticated endpoint.

Keep your data files and credentials outside version control. This repository includes no real campaign exports, account identifiers or deployment configuration. The service does not automatically load a dotenv file or local AI-client credentials. Raw adapter errors, local paths and database identifiers are excluded from HTTP error/manifest responses.

Validation and limits

npm test checks recommendation boundaries, zero-sales behavior, bid caps, denominator handling, default-data isolation, bearer authentication and real MCP calls against a loopback server. npm run build performs the TypeScript build. Optional PostgreSQL connectivity is not covered by the offline test suite.

Licensing and attribution

No new source-code license is granted with this portfolio edition. Dependency licenses remain with their respective authors. Amazon and Amazon Ads are referenced descriptively; this project is not affiliated with Amazon.