adtest-mcp

AdTest.AI MCP server

· 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 only, not through this server.)

Quick add for Claude Code:

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):

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

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