{"_id":"@adlibrary/mcp","_rev":"5-64f92b19a2187fd596359c1b121e68fb","name":"@adlibrary/mcp","dist-tags":{"latest":"0.2.1"},"versions":{"0.2.0":{"name":"@adlibrary/mcp","version":"0.2.0","keywords":["mcp","modelcontextprotocol","ads","ad-intelligence","adlibrary","facebook-ads","meta-ads"],"license":"MIT","_id":"@adlibrary/mcp@0.2.0","maintainers":[{"name":"adlibrary-m","email":"support@adlibrary.com"}],"bin":{"adlibrary-mcp":"dist/index.js"},"dist":{"shasum":"65e1f3a849583b2dbce1b31249aacedd2e8c7212","tarball":"https://registry.npmjs.org/@adlibrary/mcp/-/mcp-0.2.0.tgz","fileCount":3,"integrity":"sha512-3cmcfFRxcsreVtMnsha2zmkg12rW59rxKj/Y5b9xS5Fz9EyJ1gjZYhxCi/QbDu8ChL9TByj526KvfvjqOgqVdg==","signatures":[{"sig":"MEUCIAvpO8uhcEifuMbAskY56eESuh/YODK4sbGDpMvci+4bAiEAuUU0dgrGaOy91B1PpXAfSp+pj/qkSdpkTwGKcxJk0Ao=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":39232},"type":"module","engines":{"node":">=18"},"gitHead":"bdb58c1cbfd96f267afd173b164507b27c898372","scripts":{"build":"tsc && chmod +x dist/index.js","prepublishOnly":"npm run build"},"_npmUser":{"name":"adlibrary-m","email":"support@adlibrary.com"},"_npmVersion":"10.9.8","description":"MCP server for the adlibrary.com ad-intelligence API (Meta, Instagram, Google ATC, LinkedIn)","directories":{},"_nodeVersion":"22.22.3","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@types/node":"26.1.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp_0.2.0_1783002044976_0.5417269514956657","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@adlibrary/mcp","version":"0.2.1","description":"MCP server for the adlibrary.com ad-intelligence API (Meta, Instagram, Google ATC, LinkedIn)","license":"MIT","type":"module","bin":{"adlibrary-mcp":"dist/cli.js"},"scripts":{"build":"tsc && chmod +x dist/cli.js","prepublishOnly":"npm run build"},"engines":{"node":">=18"},"keywords":["mcp","modelcontextprotocol","ads","ad-intelligence","adlibrary","facebook-ads","meta-ads"],"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"26.1.0","typescript":"^5.7.0"},"_id":"@adlibrary/mcp@0.2.1","gitHead":"3069a6b73c75555c8b15b3d1947d3fa2f2ecc574","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-tnOgFQo7IElcdzo5LV/AFThD3ECFPU5uhBPzSmISp17wpQEkQ8PsnUP88jA4fWZYWrhYHF5KOUEgeoMY+Rin7w==","shasum":"3e5cea0016ecd66e6035a5628f8f7a80e60cba4b","tarball":"https://registry.npmjs.org/@adlibrary/mcp/-/mcp-0.2.1.tgz","fileCount":5,"unpackedSize":45848,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDXZbQqBCNvuig3DwIK89yuB5eUc+EfV17+m+WYDyjC0gIhALvtxV8mEf8Ml4irYxf+YN5Xcu9xOJDBy/A8p4EmiaDt"}]},"_npmUser":{"name":"adlibrary-m","email":"support@adlibrary.com"},"directories":{},"maintainers":[{"name":"adlibrary-m","email":"support@adlibrary.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp_0.2.1_1783002724255_0.1269467724940585"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-02T14:20:44.775Z","modified":"2026-07-02T14:32:04.562Z","0.1.0":"2026-07-02T14:13:42.759Z","0.1.1":"2026-07-02T14:16:45.065Z","0.2.0":"2026-07-02T14:20:45.160Z","0.2.1":"2026-07-02T14:32:04.444Z"},"license":"MIT","keywords":["mcp","modelcontextprotocol","ads","ad-intelligence","adlibrary","facebook-ads","meta-ads"],"description":"MCP server for the adlibrary.com ad-intelligence API (Meta, Instagram, Google ATC, LinkedIn)","maintainers":[{"name":"adlibrary-m","email":"support@adlibrary.com"}],"readme":"# adlibrary\n\nMCP (Model Context Protocol) server for the [adlibrary.com](https://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.\n\n## Requirements\n\n- An adlibrary.com **Business** subscription and an API key (format `adl_...`).\n  Create one at **[adlibrary.com/api-access](https://adlibrary.com/api-access)**.\n- Node.js 18 or newer.\n\n## Setup — Claude Desktop\n\nAdd this to your `claude_desktop_config.json` (Claude Desktop → Settings → Developer → Edit Config):\n\n```json\n{\n  \"mcpServers\": {\n    \"adlibrary\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@adlibrary/mcp\"],\n      \"env\": {\n        \"ADLIBRARY_API_KEY\": \"adl_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. You should see the adlibrary tools in the tools menu.\n\n## Setup — Cursor / other MCP clients\n\nAny 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`.\n\n## Tools\n\nFree 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.\n\n| Tool | Cost | What it does |\n|---|---|---|\n| `count_ads` | free | Market sizing: total number of ads matching filters, no results returned. Run before `search_ads`. |\n| `resolve_brand` | free | Brand name → advertiser IDs on Meta (page id), Google ATC (`AR…` id) and LinkedIn (company id). |\n| `find_advertiser_pages` | free | Find Meta advertiser pages (page_id, ad_count, verification) — required probe before `scan_winners`. |\n| `get_ad_detail` | free | Full metadata for one ad: copy, media, CTA, runtime, impressions, Meta audience breakdown. |\n| `list_saved_advertisers` | free | List brands you saved for tracking. |\n| `save_advertiser` / `update_saved_advertiser` / `delete_saved_advertiser` | free | Manage saved brands. |\n| `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. |\n| `get_advertiser_ads` | 1 credit / 30-min session | Pull a saved brand's ads across Meta + Google + LinkedIn; pagination within 30 minutes is free. |\n| `analyze_ad` | 1+ credit | AI (Gemini) creative analysis of one ad: analysis, summary, scene-marked transcription. Long videos cost more. |\n| `scan_winners` | 10 credits | Scan an advertiser's full Meta portfolio and detect winning ads (winner/loser tiers, composite scores, creative DNA diffs). |\n\n### Limits worth knowing\n\n- `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.\n- `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.\n- Impressions and spend figures are ranges/estimates, never exact disclosures.\n- All charges bill the team owner's credit balance.\n\n## Environment variables\n\n| Variable | Required | Description |\n|---|---|---|\n| `ADLIBRARY_API_KEY` | yes | Your `adl_...` API key from adlibrary.com/api-access |\n| `ADLIBRARY_BASE_URL` | no | Override the API base URL (default `https://adlibrary.com`) |\n\n## Development\n\n```bash\nnpm install\nnpm run build          # tsc → dist/\nnode dist/index.js     # run over stdio (needs ADLIBRARY_API_KEY)\nnode test/live.mjs     # live end-to-end test against the real API (spends ~2 credits)\n```\n\n## License\n\nMIT\n\n## Connect to Claude Desktop\n\n1. Open the config file (create it if missing):\n   - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n2. Add the server (get a Business-tier key from adlibrary.com → Settings → API):\n   ```json\n   {\n     \"mcpServers\": {\n       \"adlibrary\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@adlibrary/mcp\"],\n         \"env\": { \"ADLIBRARY_API_KEY\": \"adl_your_key_here\" }\n       }\n     }\n   }\n   ```\n3. Restart Claude Desktop. The adlibrary tools appear under the tools (hammer) icon.\n\nRequires Node.js ≥ 18.\n\n## Remote server (Custom Connector — no install for users)\n\nRun one container; users add it in Claude via **Settings → Connectors → Add custom connector** by pasting a URL — no Node, no config file.\n\n**Deploy (Docker):**\n```bash\ndocker build -t adlibrary-mcp .\ndocker run -d -p 8080:8080 --restart unless-stopped adlibrary-mcp\n```\nPut 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.\n\n**User setup:** paste this as the Remote MCP Server URL (the API key is the last path segment):\n```\nhttps://mcp.adlibrary.com/adl_yourkey\n```\n\n`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.\n","readmeFilename":"README.md"}