# ScraperCity - B2B Lead Generation for AI Agents

Pull leads, validate emails, find mobile numbers, and scrape business data - all from your AI agent, CLI, or code. One package: the MCP server, the CLI and the JavaScript SDK. The Python SDK is `pip install scrapercity`.

ScraperCity gives AI agents access to 15+ B2B data tools: Apollo scraping, Google Maps extraction, email finding/validation, mobile number lookup, skip tracing, ecommerce store data, criminal records, and more.

## Quick Start

### Option 1: CLI

```bash
npx scrapercity login            # enter your API key
npx scrapercity wallet           # check balance
npx scrapercity maps -q "plumbers" -l "Denver, CO"
npx scrapercity poll <runId>     # wait for results
npx scrapercity download <runId> # save CSV
```

### Option 2: MCP Server (Claude Code, Cursor, Windsurf, etc.)

Add to your MCP config (e.g. `~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "scrapercity": {
      "command": "npx",
      "args": ["-y", "--package", "scrapercity", "scrapercity-mcp"],
      "env": {
        "SCRAPERCITY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Then tell your AI: *"Find 1000 plumbers in Denver with emails using ScraperCity"*

### Option 3: Skill File (Claude Code)

Copy the skill file into your project:

```bash
npx scrapercity-mcp --print-skill > SCRAPERCITY_SKILL.md
```

Or download from: `https://scrapercity.com/agents/SKILL.md`

Then in Claude Code: *"Read SCRAPERCITY_SKILL.md and find me 2000 marketing directors at SaaS companies in California, validate their emails, and save to leads.csv"*

### Option 4: Direct API

```bash
# Start a Maps scrape
curl -X POST https://app.scrapercity.com/api/v1/scrape/maps \
  -H "Authorization: Bearer $SCRAPERCITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"searchStringsArray":["plumbers"],"locationQuery":"Denver, CO","maxCrawledPlacesPerSearch":500}'

# Check status
curl https://app.scrapercity.com/api/v1/scrape/status/RUN_ID \
  -H "Authorization: Bearer $SCRAPERCITY_API_KEY"

# Download CSV when SUCCEEDED
curl -O https://app.scrapercity.com/api/downloads/RUN_ID \
  -H "Authorization: Bearer $SCRAPERCITY_API_KEY"
```

### Option 5: JavaScript SDK

```bash
npm install scrapercity
```

```js
import { configure, wallet, dbLeads, callTool, TOOLS, openaiTools, anthropicTools } from 'scrapercity'

configure({ apiKey: process.env.SCRAPERCITY_API_KEY })
await wallet()
await dbLeads({ title: 'CEO', country: ['United States'], hasEmail: 'true', limit: 25 })

// Every tool the MCP server offers, by name, with the same arguments
await callTool('plan_search', { query: 'dentists in Austin, Texas' })

// Hand the whole tool list to OpenAI or Anthropic tool calling
const tools = openaiTools()        // or anthropicTools()
```

### Option 6: Python SDK

```bash
pip install scrapercity                 # add [langchain] or [openai] for agent tools
```

```python
from scrapercity import ScraperCity, langchain_tools
sc = ScraperCity()                      # reads SCRAPERCITY_API_KEY
sc.call_tool("query_lead_database", {"title": "CEO", "limit": 10})
tools = langchain_tools()               # LangChain / LangGraph
```

Both SDKs carry the same tool list as the MCP server, regenerated from the live API docs on every release. Guide: [scrapercity.com/sdk](https://scrapercity.com/sdk). Python package: [pypi.org/project/scrapercity](https://pypi.org/project/scrapercity/).

## Pricing (auto-generated from the live catalog — do not edit)

<!-- GENERATED:pricing:start -->
| Tool | Endpoint | Price |
|------|----------|-------|
| `scrape_apollo` | /api/v1/scrape/apollo | $0.0039 per lead |
| `scrape_website_finder` | /api/v1/scrape/website-finder | $0.0499 per contact found |
| `find_people` | /api/v1/scrape/skip-trace | $0.0199 per result (searches with 0 matches are billed as 1 result) |
| `scrape_distress_list` | /api/v1/scrape/distress-list | $0.05 per property |
| `validate_emails` | /api/v1/scrape/email-validator | $0.0017 per email |
| `scrape_maps` | /api/v1/scrape/maps | $0.0099 per business |
| `scrape_airbnb` | /api/v1/scrape/airbnb-email | $0.019 per result ($19.00 per 1,000) |
| `scrape_bizbuysell` | /api/v1/scrape/bizbuysell-scraper | $0.0099 per listing |
| `scrape_crexi` | /api/v1/scrape/crexi-scraper | $0.029 per property |
| `scrape_angi` | /api/v1/scrape/angi-angies-list-scraper | $0.0099 per listing |
| `scrape_yelp` | /api/v1/scrape/yelp-scraper | $0.0099 per result |
| `scrape_zillow_agents` | /api/v1/scrape/zillow-agents | $0.029 per agent |
| `scrape_property_lookup` | /api/v1/scrape/property-lookup | $0.15 per property (+$0.10 for owner contact) |
| `search_criminal_records` | /api/v1/scrape/criminal-records | $1.00 per search (only charged if records found) |
| `scrape_store_leads` | /api/v1/scrape/store-leads | $0.0039 per lead |
| `scrape_builtwith` | /api/v1/scrape/techstack | $4.99 per technology |
| `scrape_signals` | /api/v1/scrape/signals | $0.10 per company running ads, $0.03 per website checked, $0.05 per company hiring; minimum charge per search |
| `find_emails` | /api/v1/scrape/email-finder | $0.05 per email found (FREE if not found) |
| `find_mobiles` | /api/v1/scrape/mobile-finder | $0.25 per number found (FREE if not found) |
<!-- GENERATED:pricing:end -->

## Available Tools

| Tool | What it does | Cost |
|------|-------------|------|
| **Apollo** | B2B contacts by job title, industry, location | $0.0039/lead |
| **Google Maps** | Local businesses with phones, emails, reviews | $0.01/place |
| **Email Validator** | Verify deliverability, catch-all, MX records | $0.0036/email |
| **Email Finder** | Find business email from name + company | $0.05/contact |
| **Mobile Finder** | Phone numbers from LinkedIn or email | $0.25/input |
| **People Finder** | Skip trace by name, email, phone, address | $0.02/result |
| **Store Leads** | Shopify/WooCommerce stores with contacts | $0.0039/lead |
| **BuiltWith** | All sites using a technology | $4.99/search |
| **Criminal Records** | Background check by name | $1.00 if found |
| **Lead Database** | 3M+ B2B contacts, instant query ($149/mo plan and up) | Included |
| **Local Business Database** | Local businesses with phones, emails and ratings, instant query ($149/mo plan and up) | Included |

## How It Works

1. **Start a scrape** → get a `runId`
2. **Poll status** (or use webhooks) → wait for `SUCCEEDED`
3. **Download CSV** → leads with full contact info

Apollo scrapes usually take 15-30 minutes. All other scrapers: 1-30 minutes. Store leads are instant.

## Authentication

Get your API key at [app.scrapercity.com/dashboard/api-docs](https://app.scrapercity.com/dashboard/api-docs)

```bash
# Environment variable (recommended)
export SCRAPERCITY_API_KEY="your_key"

# Or save to config file
npx scrapercity login
```

## Webhooks

For Apollo and long-running scrapes, configure a webhook at [app.scrapercity.com/dashboard/webhooks](https://app.scrapercity.com/dashboard/webhooks) to get notified when results are ready.

## Plans

| Plan | Price | Credits |
|------|-------|---------|
| Trial | Free | $5 |
| Starter | $49/mo | $49 |
| Growth | $149/mo | $149 + 10% bonus |
| Professional | $649/mo | $649 + 30% bonus + Database API |

Buy additional credits anytime. [scrapercity.com/pricing](https://scrapercity.com/pricing)

## Links

- [Agent Docs](https://scrapercity.com/agents) - setup guide
- [API Reference](https://scrapercity.com/api-docs) - full documentation
- [SDK guide](https://scrapercity.com/sdk) - JavaScript and Python SDKs
- [Python SDK on PyPI](https://pypi.org/project/scrapercity/) - `pip install scrapercity`
- [Skill File](https://scrapercity.com/agents/SKILL.md) - for Claude Code
- [MCP Server Listing](https://scrapercity.com/agents) - configuration

## License

MIT