adhistory-mcp

An MCP server that gives AI agents (Claude Desktop, Claude Code, Cursor and any other MCP client) eleven data tools for jobs people actually ask an assistant to do:

• Competitor Google ads: the Search, YouTube, Shopping and Display ads any company runs, from the Google Ads Transparency Center.
• App reviews: App Store and Google Play reviews, filterable to 1-2 star complaints.
• Job postings: open jobs from Workday career sites, Greenhouse, Lever and Ashby boards, and remote jobs from six remote job boards (Remotive, Remote OK, We Work Remotely, Jobicy, Himalayas, Arbeitnow) with pay parsed.
• PDF tables: tables from PDF links as rows, plus CSV and Excel.
• Bank statements: statement PDFs as transactions, balances and a balance check.
• Invoices: invoice PDFs as number, dates, vendor, totals, tax and line items.
• Email list cleaning: syntax, MX, disposable, role-account and typo checks.
• Website screenshots: full-page or first-screen images of public pages.
• Broken links: crawl a site and list broken links, images and scripts.

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")
• "Find remote Python jobs posted this week that pay at least $120k." → remote_jobs(search_text="python", posted_within_days=7, min_yearly_salary=120000)
• "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.
• remote_jobs returns what the six remote boards list right now, not every remote job on the web. Pay is parsed from the posting where the board has no pay field; currencies are not converted.

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