adlibrary

MCP (Model Context Protocol) server for the adlibrary.com ad-intelligence API. Gives Claude Desktop, Cursor, or any MCP client tools to research ads across Meta (Facebook/Instagram), Google Ads Transparency Center, LinkedIn: search creatives, resolve brands to advertiser IDs, scan advertisers for winning ads, size ad markets, and AI-analyze single ads.

Requirements

• An adlibrary.com Business subscription and an API key (format adl_...). Create one at adlibrary.com/api-access.
• Node.js 18 or newer.

Setup — Claude Desktop

Add this to your claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):

{
  "mcpServers": {
    "adlibrary": {
      "command": "npx",
      "args": ["-y", "@adlibrary/mcp"],
      "env": {
        "ADLIBRARY_API_KEY": "adl_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. You should see the adlibrary tools in the tools menu.

Setup — Cursor / other MCP clients

Any MCP client that supports stdio servers works with the same command (npx -y @adlibrary/mcp) and the ADLIBRARY_API_KEY environment variable. In Cursor: Settings → MCP → Add new MCP server, command type stdio.

Tools

Free tools cost no credits; paid tools state their cost. The server's tool descriptions steer the model to run the free probes before spending credits.

| Tool | Cost | What it does | |---|---|---| | count_ads | free | Market sizing: total number of ads matching filters, no results returned. Run before search_ads. | | resolve_brand | free | Brand name → advertiser IDs on Meta (page id), Google ATC (AR… id) and LinkedIn (company id). | | find_advertiser_pages | free | Find Meta advertiser pages (page_id, ad_count, verification) — required probe before scan_winners. | | get_ad_detail | free | Full metadata for one ad: copy, media, CTA, runtime, impressions, Meta audience breakdown. | | list_saved_advertisers | free | List brands you saved for tracking. | | save_advertiser / update_saved_advertiser / delete_saved_advertiser | free | Manage saved brands. | | search_ads | 1 credit/call | Multi-platform ad search with 25+ filters (media type, geo, run time, engagement, CTA, sort). Each page costs 1 credit. | | get_advertiser_ads | 1 credit / 30-min session | Pull a saved brand's ads across Meta + Google + LinkedIn; pagination within 30 minutes is free. | | analyze_ad | 1+ credit | AI (Gemini) creative analysis of one ad: analysis, summary, scene-marked transcription. Long videos cost more. | | scan_winners | 10 credits | Scan an advertiser's full Meta portfolio and detect winning ads (winner/loser tiers, composite scores, creative DNA diffs). |

Limits worth knowing

• search_ads: max 60 results per page (upstream hard limit), max page 100, rate limit 10 calls/min, e-commerce ads only for API keys, LinkedIn caps at 25 results.
• scan_winners: one concurrent scan per user; takes 1–5 minutes; auto-refunds on no-ads/upstream errors — but a valid-but-wrong page_id still charges, so confirm the page with find_advertiser_pages first.
• Impressions and spend figures are ranges/estimates, never exact disclosures.
• All charges bill the team owner's credit balance.

Environment variables

| Variable | Required | Description | |---|---|---| | ADLIBRARY_API_KEY | yes | Your adl_... API key from adlibrary.com/api-access | | ADLIBRARY_BASE_URL | no | Override the API base URL (default https://adlibrary.com) |

Development

npm install
npm run build          # tsc → dist/
node dist/index.js     # run over stdio (needs ADLIBRARY_API_KEY)
node test/live.mjs     # live end-to-end test against the real API (spends ~2 credits)

License

MIT

Connect to Claude Desktop

1. Open the config file (create it if missing):
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the server (get a Business-tier key from adlibrary.com → Settings → API):

   {
     "mcpServers": {
       "adlibrary": {
         "command": "npx",
         "args": ["-y", "@adlibrary/mcp"],
         "env": { "ADLIBRARY_API_KEY": "adl_your_key_here" }
       }
     }
   }

3. Restart Claude Desktop. The adlibrary tools appear under the tools (hammer) icon.

Requires Node.js ≥ 18.

Remote server (Custom Connector — no install for users)

Run one container; users add it in Claude via Settings → Connectors → Add custom connector by pasting a URL — no Node, no config file.

Deploy (Docker):

docker build -t adlibrary-mcp .
docker run -d -p 8080:8080 --restart unless-stopped adlibrary-mcp

Put it behind a TLS reverse proxy (Traefik/Caddy) at e.g. https://mcp.adlibrary.com. It's a thin passthrough to the adlibrary.com API — negligible load, stateless, scales to any number of users on one instance.

User setup: paste this as the Remote MCP Server URL (the API key is the last path segment):

https://mcp.adlibrary.com/adl_yourkey

GET /health returns {"status":"ok"} for orchestrators. The key never persists server-side — it's read from the URL per request and forwarded as the API Bearer token.