ai.adtest/adtest-mcp
AI-only ad scoring for Claude: score image, video or text ads on 13 dimensions before you spend.
Open source Open in the app JSON README (API)
About
AI-only ad scoring for Claude: score image, video or text ads on 13 dimensions before you spend.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- ai.adtest
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.1.0
- Last push
- 2026-09-02T15:26:49Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-09-01 22:00:54
- Updated
- 2026-09-01 22:00:54
- Origin id
ai.adtest/adtest-mcp
README
# AdTest.AI MCP server
[](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).