adhistory-mcp

An MCP server that gives AI agents (Claude, Cursor and any other MCP client) ten data tools: competitor ads from the Google Ads Transparency Center, App Store and Google Play reviews, job listings from Workday, Greenhouse, Lever and Ashby, tables, invoices and bank statements from PDF links, email list cleaning, website screenshots and broken link checks.

Each tool runs one public Apify Actor on your own Apify account and returns the results as JSON, trimmed so they fit in an agent's context. You need a free Apify API token. You pay only the Actor's per-result price, which at the default limits is a few cents or less per call.

Quick start

1. Create a free Apify account at https://console.apify.com/sign-up.
2. Copy your API token: console.apify.com → Settings → API & Integrations.
3. Add the server to your MCP client (examples below). It runs locally over stdio with uvx, so you need uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh on macOS/Linux, or brew install uv).

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "adhistory": {
      "command": "uvx",
      "args": ["adhistory-mcp"],
      "env": { "APIFY_TOKEN": "apify_api_your_token_here" }
    }
  }
}

Restart Claude Desktop. The tools appear under the tools icon.

Claude Code

claude mcp add adhistory --env APIFY_TOKEN=apify_api_your_token_here -- uvx adhistory-mcp

Cursor

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "adhistory": {
      "command": "uvx",
      "args": ["adhistory-mcp"],
      "env": { "APIFY_TOKEN": "apify_api_your_token_here" }
    }
  }
}

Other clients

Any MCP client that can launch a stdio server works: command uvx, argument adhistory-mcp, environment variable APIFY_TOKEN. Without uv: pip install adhistory-mcp, then run adhistory-mcp.

Tools

Each Actor also charges $0.00005 per run start. Prices are the Actors' public Apify Store prices at the time of writing; the Store page of each Actor is the source of truth.

Example prompts

• "What Google Search ads is hubspot.com running in the US right now? Group them by message." → competitor_google_ads(domains=["hubspot.com"], country="US", platform="search", only_active_ads=true)
• "Which of these 20 domains advertise on Google?" → competitor_google_ads(domains=[...], mode="advertiserCheck")
• "Summarize the last 50 one- and two-star reviews of Notion on iOS and Android." → app_reviews(apps=["notion", "notion.id"], max_reviews_per_app=25, max_rating=2)
• "List NVIDIA's remote software jobs posted this week." → workday_jobs(career_site_urls=["https://nvidia.wd5.myworkdayjobs.com/NVIDIAExternalCareerSite"], search_text="software", location_contains="Remote", posted_within_days=7)
• "Which data roles are open at Airbnb and Palantir?" → ats_jobs(boards=["https://boards.greenhouse.io/airbnb", "https://jobs.lever.co/palantir"], search_text="data")
• "Pull the table on pages 1-3 of this PDF into rows." → pdf_tables(pdf_urls=["https://.../report.pdf"], pages="1-3")
• "Total the debits in this statement by merchant." → bank_statement(pdf_urls=["https://.../statement.pdf"])
• "Which of these emails will likely bounce?" → clean_email_list(emails=[...])
• "Screenshot our pricing page on mobile." → website_screenshot(urls=["example.com/pricing"], device="mobile")
• "Find broken links on example.com." → broken_links(start_urls=["https://example.com"])

Cost control

• Defaults are small, so a typical call costs well under $0.10.
• Every run is capped by Apify's maxTotalChargeUsd, $0.50 per call by default. Set the environment variable APIFY_MAX_CHARGE_USD (for example 2) to allow larger runs.
• Free Apify accounts include monthly platform credit, which covers many small calls.

Limits

• Calls are synchronous and Apify stops waiting after 300 seconds, so very large requests fail with a clear message; ask for fewer results instead.
• Responses are trimmed for the agent: long text fields are shortened, nested lists (table rows, transactions) are capped, and at most about 60,000 characters of JSON are returned. Full tables and statements are in the CSV/Excel links the PDF tools return.
• clean_email_list works at DNS level. It does not connect to the mail server, so it cannot tell whether a specific mailbox exists.
• The PDF tools need text-based PDFs at public URLs; scanned images are not read. Local files must be uploaded somewhere public first.
• competitor_google_ads reads what Google publishes in the Transparency Center. Google does not publish ad spend, keywords or click data.
• Pages behind a login are not supported by website_screenshot and broken_links.

Privacy

The server runs on your machine. Inputs go only to the Apify API under your account, and the token is sent only in the Authorization header to api.apify.com. Results are stored in your Apify account's storage under its normal retention.

Development

uv sync --group dev
uv run pytest
uv run adhistory-mcp   # starts the stdio server

License

MIT