Scrapercity Cli

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.

Start Here (no API key needed)

npx scrapercity start "dentists in Austin"

Or have your agent call the start_here MCP tool, or GET https://app.scrapercity.com/api/v1/start?query=.... With no key you get a guided tour: what ScraperCity is, how to sign up, the plans and the trial with their live terms, and real searches with live counts. With a key it plans for your account and returns the exact next call.

The trial, plainly: The trial is real usage, not a demo or a free tier: $5 of credit for 7 days that works on every tool and database at the normal prices, so you can pull real records on day one and judge the data. A card is required at signup. When the 7 days end, the plan picked at signup starts; cancel before then from billing and nothing more is charged. If the credit runs out sooner, database pulls wait (nothing is charged for them); a scraper run that goes past the credit starts the plan early. Planning searches and checking counts are free. start_here returns the live terms.

Quick Start

Option 1: CLI

npx scrapercity login            # enter your API key

npx scrapercity wallet # check balance npx scrapercity maps -q "plumbers" -l "Denver, CO" npx scrapercity poll # wait for results npx scrapercity download # save CSV

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

Add to your MCP config (e.g. ~/.claude/claude_desktop_config.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:

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

# 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

npm install scrapercity

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

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

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. Python package: pypi.org/project/scrapercity.

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

Available Tools

Before You Send

Leads from any database: check them before outreach. Every record carries email_check_status (our own email checker: valid, valid_catch_all, invalid, unknown, not_checked): send ONLY to valid emails checked in the last 30 days (email_checked_on), and put every other email through validate_emails first. For people (Lead Database), pass replaceLeftContacts: true to query_lead_database; the response adds replacement.run_id, a run that checks every email and swaps each person who has left for the person in that role now. Wait for it with check_run_status, then send the CSV from download_results ($0.02 per contact replaced, free on the $649 plan). At minimum, run the emails through validate_emails and send only to the valid ones.

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

# 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 to get notified when results are ready.

Plans

Buy additional credits anytime. scrapercity.com/pricing

Links

• Agent Docs - setup guide
• API Reference - full documentation
• SDK guide - JavaScript and Python SDKs
• Python SDK on PyPI - pip install scrapercity
• Skill File - for Claude Code
• MCP Server Listing - configuration

License

MIT