SpyWinAds MCP server

Check Facebook video ads from ChatGPT, Claude, Cursor or your own scripts: how old a video ad really is, and every store running the same video.

• Remote server: https://spywinads.com/mcp (Streamable HTTP)

• Auth: OAuth 2.1 (sign in with your SpyWinAds account), or an API key in the Authorization header

• Read-only. 5 tools. Free plan: 30 calls a day.

• Docs: spywinads.com/developers

This repository only documents the hosted server. There is nothing to install.

Tools

All tools are annotated readOnlyHint: true, destructiveHint: false. Scopes: ads:read (look-ups) and product:export (CSV).

Related MCP server: Facebook Ads Library MCP

Connect

ChatGPT — open Plugins in the left sidebar → More (top right) → Add custom MCP server → paste https://spywinads.com/mcp. When a tool needs your account, ChatGPT asks you to sign in to SpyWinAds and click Allow.

Claude.ai / Claude Desktop — Customize → Connectors → Add custom connector → paste https://spywinads.com/mcp → choose Sign in when needed.

Claude Code

claude mcp add --transport http spywinads https://spywinads.com/mcp
# then run /mcp inside Claude Code to sign in

Cursor / VS Code / Windsurf (API key from SpyWinAds Settings → API & MCP)

{
  "mcpServers": {
    "spywinads": {
      "url": "https://spywinads.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Never put a key in a URL. Keys and connected apps can be revoked any time in SpyWinAds Settings → API & MCP.

Example prompts

• "Is this video ad new or an old video brought back? https://www.facebook.com/ads/library/?id=1014622548199238"

• "What Facebook video ads is zenblux.com running, and how many other stores use the same videos?"

• "Copy this Shopify product into a CSV I can import: https://www.allbirds.com/products/mens-tree-runners"

REST API

Same tools over HTTPS for scripts, n8n and GPT Actions:

curl -H "Authorization: Bearer YOUR_KEY" "https://spywinads.com/api/v1/store?domain=example.com"

Endpoints: /api/v1/video?ad= · /api/v1/store?domain= · /api/v1/page?page= · /api/v1/product?url= · /api/v1/research/video-reuse. OpenAPI: https://spywinads.com/api/v1/openapi.json. Errors are application/problem+json (RFC 9457); limits come back in RateLimit / Retry-After headers.

Data and limits

• Meta (Facebook, Instagram) ads shown in the US, from the SpyWinAds library (ads scanned by SpyWinAds users).

• Counts are minimums of ads observed, not sales. No ad spend, reach, orders or revenue data.

• "Earliest store" means earliest in the library, not the verified owner of the video.

• Each call returns what the free SpyWinAds web tools show; there is no search across the whole library.

• Limits: free 30 calls a day (resets 00:00 UTC+7), 20 calls a minute.

Security and privacy

• OAuth 2.1 with PKCE (S256), protected resource metadata (RFC 9728) at /.well-known/oauth-protected-resource/mcp, authorization server metadata (RFC 8414), dynamic client registration and client ID metadata documents. Access tokens last 1 hour; refresh tokens rotate.

• Tokens and keys are stored only as SHA-256 hashes. Tokens are bound to https://spywinads.com/mcp.

• We log the tool name, success or error and the calling app, not your prompts. Privacy policy: spywinads.com/privacy.

Support

support@spywinads.com · ATT ECOMMERCE COMPANY LIMITED, Hanoi, Vietnam