ad-intelligence-mcp

MCP server for searching and analyzing ads from Meta Ad Library, Google Ads Transparency Center, and LinkedIn Ads Library.

Installation

• NPX (recommended):

npx -y ad-intelligence-mcp

• Global install:

npm i -g ad-intelligence-mcp
ad-intelligence-mcp

Configuration

Set environment variables (see .env.example). At minimum provide META_ACCESS_TOKEN for Meta Ad Library queries.

• Load via shell or MCP client config.
• The server logs to stderr and communicates MCP over stdio.

Environment variables

• META_ACCESS_TOKEN (required for Meta)
• GOOGLE_ADS_CREDENTIALS (optional)
• LINKEDIN_CREDENTIALS (optional)
• CACHE_TTL (default: 3600 seconds)
• MAX_CONCURRENT_REQUESTS (default: 5)
• DEBUG (set to 1 to enable)

Usage with Claude Desktop

Add to your config:

{
  "mcpServers": {
    "ad-intelligence": {
      "command": "npx",
      "args": ["-y", "ad-intelligence-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Tools

• search_company_ads:
  • params: company_name (string, required), platforms (array), country (string), limit (number)
• search_industry_ads:
  • params: industry_type (string, required), platforms, country, limit
• get_ad_insights:
  • params: query (string, required), analysis_depth ("basic"|"detailed")

Rate limits and behavior

• Meta API uses pagination with automatic retries and backoff. Rate limit target: ~200 calls/hour.
• Google/LinkedIn scraping is best-effort and disabled unless puppeteer is installed (optional dependency). Respect robots.txt and delays.
• Caching: in-memory default TTL 1 hour.
• Timeout: 30 seconds per request.
• Graceful degradation: failures on one platform do not block others.

Development

npm i
npm run build
npm start

• Shebang and bin mapping allow npx ad-intelligence-mcp to run.
• TypeScript strict mode is enabled.
• Logging can be enabled with DEBUG=1.

Troubleshooting

• Missing Meta token: responses include an error for meta platform.
• Google/LinkedIn returning empty: install puppeteer or provide credentials if available.
• MCP client cannot connect: ensure stdio is not being intercepted; check stderr logs.

Security

• Tokens are never logged.
• All HTTP requests use HTTPS and timeouts.
• Input parameters are validated.

Contributing

PRs welcome. Please run npm run build and include tests for utilities where applicable.