# AdTest.AI MCP server

[![npm](https://img.shields.io/npm/v/adtest-mcp)](https://www.npmjs.com/package/adtest-mcp) · Registry name: `ai.adtest/adtest-mcp` · License: MIT

Adds a single **`analyze_advert`** tool to Claude (Desktop, Code, or any MCP client) that
runs AdTest.AI's **AI-only** 13-dimension analysis of an advert — **image, video, or text** —
and returns a detailed scoring report. (Human-panel validation is available in the
[web app](https://app.adtest.ai) only, not through this server.)

Quick add for Claude Code:

```bash
claude mcp add adtest -e ADTEST_API_KEY=adk_your_key_here -- npx -y adtest-mcp
```

## Setup

1. **Get an API key:** sign in at <https://app.adtest.ai> → the **Developer** (gear)
   icon → **Generate key**. Make sure your wallet has funds — each successful
   analysis costs **$1**.

2. **Add the server to your Claude config** (Claude Desktop:
   `claude_desktop_config.json`; Claude Code: `.mcp.json`):

   ```json
   {
     "mcpServers": {
       "adtest": {
         "command": "npx",
         "args": ["-y", "adtest-mcp"],
         "env": { "ADTEST_API_KEY": "adk_your_key_here" }
       }
     }
   }
   ```

   Or run it from a local checkout (after `npm install` in this folder):

   ```json
   {
     "mcpServers": {
       "adtest": {
         "command": "node",
         "args": ["/absolute/path/to/mcp-server/index.js"],
         "env": { "ADTEST_API_KEY": "adk_your_key_here" }
       }
     }
   }
   ```

3. **Restart Claude**, then just ask:
   - *“Analyze this advert: https://example.com/ad.jpg”*
   - *“Analyze this ad video file: /Users/me/promo.mp4”*
   - *“Score this ad copy: 50% off all shoes this weekend — shop now.”*

## The tool

`analyze_advert` — provide **one** of:

| arg | meaning |
|-----|---------|
| `url` | public URL of an image or video advert (we download it) |
| `file_path` | local image/video file to upload |
| `text` | ad copy to analyze |
| `brand_url` *(optional)* | advertiser website — improves brand/logo detection |

Returns the AI analysis text plus the amount charged and your remaining balance.

## How it works (async — so video works)

The server submits the job to `POST /developer/ai-analysis/jobs`, gets a
`job_id` back immediately, then polls `GET /developer/ai-analysis/jobs/{job_id}`
every few seconds until it's `complete` or `failed`. This is why **video works**:
a single synchronous request would be cut off by the CDN edge timeout (~100s),
but video analysis can take several minutes. You're charged **once, on success**,
when the job completes — a failed job is never billed.

## Notes

- Registered in the official MCP Registry as `ai.adtest/adtest-mcp`.

- Auth is the `x-api-key` header, set from `ADTEST_API_KEY`.
- Endpoint defaults to `https://app.adtest.ai/adtest-api`; override with
  `ADTEST_API_BASE` for staging.
- Poll ceiling defaults to 15 min; override with `ADTEST_POLL_TIMEOUT_MS`
  (milliseconds) for very long video.
- Rate limits: 30 submits/min and 2000/day per key (60/min per IP); polling is
  generous (240/min) and handled for you.
- Errors come back as readable text: `invalid_api_key`, `insufficient_funds`,
  `no_creative`, `invalid_url`, `unsupported_media_type`, `too_many_requests`,
  `analysis_failed` (the last is **not** charged).
- Requires Node ≥ 18.

## Links

- Product: <https://adtest.ai>
- Setup guide and FAQ: <https://adtest.ai/mcp/>
- App and API keys: <https://app.adtest.ai>
- Issues: <https://github.com/menaker/adtest-mcp/issues>

## License

MIT — see [LICENSE](LICENSE).