Metadata-Version: 2.5
Name: adhistory-mcp
Version: 0.2.1
Summary: MCP server for AI agents: competitor Google ads, App Store/Google Play reviews, jobs from Workday/Greenhouse/Lever/Ashby and remote job boards, PDF tables, bank statements, invoices, email list cleaning, screenshots and broken links, via Apify.
Project-URL: Homepage, https://github.com/OBrandon/adhistory-mcp
Project-URL: Repository, https://github.com/OBrandon/adhistory-mcp
Project-URL: Issues, https://github.com/OBrandon/adhistory-mcp/issues
Project-URL: Apify Store, https://apify.com/adhistory
Project-URL: MCP Registry, https://registry.modelcontextprotocol.io/v0/servers?search=io.github.OBrandon/adhistory-mcp
Author: adhistory
License-Expression: MIT
License-File: LICENSE
Keywords: ads-transparency-center,ai-agents,apify,app-reviews,app-store,ashby,bank-statement,broken-link-checker,claude,competitor-ads,cursor,email-list-cleaning,email-validation,google-ads,google-play,greenhouse,invoice-parser,job-postings,jobs-api,lever,llm-tools,mcp,mcp-server,model-context-protocol,pdf-tables,pdf-to-excel,remote-jobs,screenshot,web-scraping,workday
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Office/Business
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# adhistory-mcp

<!-- mcp-name: io.github.OBrandon/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](https://apify.com/adhistory) 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`](https://docs.astral.sh/uv/), 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):

```json
{
  "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

```bash
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):

```json
{
  "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

| Tool | What it returns | Price per 1,000 results | Default size | Typical time |
|---|---|---|---|---|
| `competitor_google_ads` | Ads a company runs on Google Search, YouTube, Shopping, Maps, Play and Display, from the Google Ads Transparency Center: headline and description of text ads, format, first/last shown, days running, countries, link. Or one summary row per domain (`mode: advertiserCheck`). | $1.00 | 20 ads per advertiser | 20-90 s |
| `app_reviews` | App Store and Google Play reviews: rating, title, text, date, app version, developer reply. Star filter for complaints only. | $0.10 | 20 per app | 10-40 s |
| `workday_jobs` | Open jobs from any `*.myworkdayjobs.com` career site; optional description, pay range, apply link. | $1.00 | 20 jobs | 10-60 s |
| `ats_jobs` | Open jobs from Greenhouse, Lever and Ashby boards: department, location, remote flag, pay when published. | $1.50 | 20 jobs | 5-30 s |
| `remote_jobs` | Remote jobs from Remotive, Remote OK, We Work Remotely, Jobicy, Himalayas and Arbeitnow, deduplicated: company, allowed location, posted date, apply link, pay parsed to min/max/currency/period and a yearly figure. Filters for keywords, location, age and minimum pay. | $1.00 | 20 jobs | 5-30 s |
| `pdf_tables` | Tables from PDF links as rows, plus CSV and Excel links. | $2.00 | 10 tables | 10-60 s |
| `bank_statement` | Bank statement PDFs as balances, totals, a balance check and transactions, plus Excel. | $15.00 | 5 statements | 10-40 s |
| `invoice` | Invoice PDFs as number, dates, vendor, totals, tax and line items, plus Excel. | $5.00 | 10 invoices | 10-30 s |
| `clean_email_list` | Syntax, MX record, disposable, role account and typo checks per email, with a valid/invalid/risky/unknown result. | $0.20 | up to 1,000 emails | 5-30 s |
| `website_screenshot` | Full-page or first-screen PNG/JPEG of public pages, returned as image URLs. | $1.00 | 1 per URL (max 10) | 10-30 s per page |
| `broken_links` | Crawls a site and reports broken links, images and scripts with status, error and the pages they appear on. | $1.00 | 10 pages, problems only | 20-120 s |

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

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

## License

MIT
