Integration Guide
Give any AI agent the ability to scrape B2B leads, find and validate emails, look up phone numbers, and query contact databases - all through MCP, CLI, or direct API calls.
An AI agent workflow is a multi-step automated sequence where an agent plans, selects tools, executes API calls, and handles results - all without a human directing each step. Unlike a simple chat prompt that returns a single answer, an agentic workflow lets the model reason across steps: check your wallet balance, run a scrape, poll for completion, download the CSV, and pass results into the next tool.
For B2B sales and marketing, this means an agent can receive one plain-English instruction - "find 1,000 marketing directors at fintech companies, validate their emails, and save to leads.csv" - and autonomously handle every API call required to complete it. ScraperCity exposes all 25 of its B2B data tools as MCP tools, CLI commands, and REST endpoints so any agent can call them in sequence.
The key difference from traditional automation is adaptability. If an Apollo scrape returns fewer results than expected, the agent can adjust filters, try a broader search, or switch to the Lead Database - without you writing conditional logic for every case. You describe the outcome; the agent figures out the steps.
Claude Code
Cursor
Windsurf
Cline
Gemini CLI
GitHub Copilot CLI
Perplexity
Devin
OpenAI Codex
n8n
Any MCP Client
Any agent that supports the Model Context Protocol or can run shell commands works with ScraperCity. The MCP config JSON is identical across all clients - only the file path differs per tool.
Add ScraperCity as a tool your AI agent can call directly. Works with any MCP-compatible client. The agent sees every ScraperCity scraper as a named tool it can invoke in plain English.
Universal MCP config block (same JSON for all clients):
{
"mcpServers": {
"scrapercity": {
"command": "npx",
"args": ["-y", "--package", "scrapercity", "scrapercity-mcp"],
"env": {
"SCRAPERCITY_API_KEY": "your_api_key_here"
}
}
}
}Config file location by client:
| Client | Config file path |
|---|---|
| Claude Code | ~/.claude/mcp.json or .mcp.json in project root |
| Cursor | ~/.cursor/mcp.json or <project>/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
| Cline / VS Code | .vscode/mcp.json in workspace |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) |
Add via Claude Code CLI (one-liner):
claude mcp add scrapercity --transport stdio -e SCRAPERCITY_API_KEY=your_api_key_here -- npx -y --package scrapercity scrapercity-mcpAfter adding the config, fully quit and relaunch your editor. The agent gets access to every ScraperCity scraper: Apollo contacts ($0.0039/lead), Google Maps businesses ($0.01/place), email validation ($0.0036/email), email finder ($0.05/contact), mobile finder ($0.25/input), people finder ($0.02/result), store leads, BuiltWith, criminal records, and more - plus the 3M+ contact Lead Database on the $649/mo plan.
A command-line tool that turns 20-line API requests into 5-word commands. Works with any agent that can execute shell commands - including agents that do not support MCP.
# Install and authenticate
npx scrapercity login
# Check balance
npx scrapercity wallet
# Scrape Google Maps
npx scrapercity maps -q "plumbers" -l "Denver, CO" --limit 500
# Poll until done
npx scrapercity poll <runId>
# Download CSV
npx scrapercity download <runId> -o plumbers.csvThe CLI is the best option for Devin, GitHub Copilot Agent Mode, and any automated pipeline that runs in a shell environment. No Node configuration required beyond a one-time npx scrapercity login.
A compressed doc your agent reads once to understand every ScraperCity endpoint, input format, cost, and error code. Drop it in your project and go. Useful for agents that call the REST API directly without MCP.
# Download the skill file into your project
curl -o SCRAPERCITY_SKILL.md https://scrapercity.com/agents/SKILL.md
# Then tell your agent:
"Read SCRAPERCITY_SKILL.md and find me 2000 marketing directors
at SaaS companies in California. Validate their emails and
save the results to leads.csv"| Tool | What It Does | Cost | Speed |
|---|---|---|---|
| Apollo | B2B contacts by title, industry, location | $0.0039/lead | 11-48+ hours |
| Google Maps | Local businesses with phones, emails, reviews | $0.01/place | 5-30 min |
| Email Validator | Verify deliverability, catch-all, MX records | $0.0036/email | 1-10 min |
| Email Finder | Business email from name + company | $0.05/contact | 1-10 min |
| Mobile Finder | Phone numbers from LinkedIn or email | $0.25/input | 1-5 min |
| People Finder | Skip trace by name, email, phone, address | $0.02/result | 2-10 min |
| Store Leads | Shopify/WooCommerce stores with contacts | $0.0039/lead | Instant |
| BuiltWith | All sites using a technology | $4.99/search | 1-5 min |
| Criminal Records | Background check by name | $1.00 if found | 2-5 min |
| Airbnb Email | Host emails by city or listing URL | $0.019/listing | 10-30 min |
| YouTube Email | Business emails for YouTube channels | Per channel | 5-15 min |
| Website Finder | Contact info from website domains | Per domain | 5-15 min |
| Yelp | Business listings from Yelp | $0.01/listing | 5-15 min |
| Angi | Service providers from Angie's List | $0.01/listing | 5-15 min |
| Zillow Agents | Real estate agent listings | Per agent | 5-15 min |
| BizBuySell | Businesses for sale listings | $0.01/listing | 5-15 min |
| Crexi | Commercial real estate listings | $0.029/listing | 5-15 min |
| Property Lookup | Property data + owner contact | $0.15/address | 2-10 min |
| Lead Database | 3M+ B2B contacts, instant query | $649/mo plan | Instant |
“Find 2000 marketing directors at SaaS companies in California, validate their emails, find their mobile numbers, and save everything to leads.csv”
The agent chains 3 tools: Apollo scrape → email validation → mobile finder. Downloads and merges the CSVs automatically.
“Scrape all plumbers in Denver from Google Maps, then find the business owner's email for each one”
Maps scrape returns businesses. Agent extracts names + domains, feeds them to email finder, merges results.
“Check my ScraperCity balance, then pull 500 Shopify stores in the US that have Instagram accounts and export to CSV”
Agent calls wallet first to verify credits, then runs store-leads with the Instagram filter, downloads results.
“Query the lead database for all VPs of Sales at companies with 50-200 employees in New York. Paginate through every page and save to nyc-vps.csv”
Agent reads the pagination response, loops through all pages at 100 leads each, combines into a single CSV.
“Find all Shopify stores selling pet products, look up the owner's LinkedIn email for each, validate deliverability, and flag any catch-all domains”
Agent runs store-leads with a pet category filter, batches domains into email finder, then passes each result to email validator. Catch-all status comes back in the validation response.
“I have a list of 300 company domains in domains.txt. Find the CEO email for each, validate them, and output only the verified ones to verified-ceos.csv”
Agent reads the local file, feeds domains to email finder in batches, runs validation on each result, filters by deliverable status, writes the final CSV.
These are the most frequently used multi-step patterns. Each one chains two or more ScraperCity tools in sequence. The agent handles the sequencing, polling, and data merging automatically - you just describe the end goal.
This is the most common agentic workflow. Apollo delivers in 11-48+ hours, so configure a webhook before running. Email validation completes in 1-10 minutes per batch.
Google Maps scrapes complete in 5-30 minutes. Good for agencies targeting local service businesses (HVAC, plumbing, roofing, legal, dental).
BuiltWith returns the full list of domains using a tech ($4.99/search). Website finder then pulls contact data per domain. Best for outbound targeting competitors' customers.
Store leads data is instant and returns from a cached database. Combine with email finder for fully enriched ecommerce prospect lists.
AI agent workflows can encounter avoidable errors if not set up correctly. These tips cover batching, async handling, and cost control.
Batch email validation requests. Instead of validating one email at a time, pass the full list from an Apollo or Maps scrape to the email validator in a single run. Agents should check if the ScraperCity endpoint accepts bulk input before making individual calls.
Use Store Leads for fast iteration. Store leads data is returned instantly from a cached database at $0.0039/lead - the same price as Apollo. When your workflow needs quick results (demos, tests, same-day campaigns), start with store leads before committing to Apollo's async delivery.
Prefer the Lead Database for targeted ICP searches. If you are on the $649/mo plan and you know your exact buyer persona (title + company size + location), query the Lead Database first. Results are instant and paginate at 100 leads per page up to 100,000 per day - no waiting.
Tell the agent to check wallet balance before any large run. A $10 wallet balance will stop mid-workflow on a 5,000-lead Apollo scrape. A balance check at the start of the workflow costs nothing and prevents a 402 error 30 minutes in.
For Apollo: trigger once, then wait for the webhook. Apollo scrapes take 11-48+ hours. Have your agent submit the scrape job and record the runId, then wait for the webhook callback at app.scrapercity.com/dashboard/webhooks. Polling in a loop wastes credits and is blocked by duplicate protection after 30 seconds.
Use separate API keys per agent or environment. You can create multiple API keys from app.scrapercity.com/dashboard/api-docs. Assign one key per agent so you can track spend per workflow and revoke access for a single agent without affecting others.
Most MCP and API connection issues have one of five causes. Work through these in order before opening a support ticket.
⚠MCP server not appearing in agent / tools list is empty
Fully quit and relaunch your editor. Closing the window is not enough - use Quit from the menu or kill the process. Then reopen. The MCP server list is loaded at startup.
⚠"connection closed" or "spawn npx ENOENT"
Node.js is either not installed or the wrong version is on PATH. Run node --version in your terminal. Anything below Node 18 can cause issues with npx package resolution. Use nvm to install and pin Node 20: nvm install 20 && nvm use 20 && nvm alias default 20.
⚠401 Unauthorized from API
Your API key is invalid or missing. Verify it at app.scrapercity.com/dashboard/api-docs. In the MCP config, make sure the key is in the env block with no surrounding quotes or extra spaces. Run npx scrapercity wallet in your terminal to confirm the key works outside the editor.
⚠402 Payment Required mid-workflow
Your wallet balance ran out. Top up at app.scrapercity.com. Add a wallet balance check step at the start of any agent workflow to catch this before the expensive calls begin.
⚠429 or duplicate request blocked
Duplicate protection blocks identical requests within 30 seconds. If your agent is retrying the same call in a tight loop, add a delay or check the run status endpoint instead of resubmitting. For Apollo, use the webhook instead of polling.
⚠Apollo run returns zero results
Apollo scrapes with very narrow filters (tight title + industry + location combo) can return empty. Have the agent broaden the search - remove the location filter, widen the title list, or increase the company size range. Check the run status response for any filter warnings.
⚠Config changes not taking effect in Cursor or Windsurf
Both Cursor and Windsurf load MCP config at startup. Save the config file, then fully quit and relaunch the application. Cursor reads from ~/.cursor/mcp.json. Windsurf reads from ~/.codeium/windsurf/mcp_config.json. Verify the path is correct for your OS.
Apollo scrapes typically take 11-48+ hours. Configure a webhook at app.scrapercity.com/dashboard/webhooks instead of having your agent poll in a loop. All other scrapers complete in minutes.
Always have the agent check wallet balance before running expensive scrapes. This prevents 402 errors mid-workflow.
For Claude Code, add the SCRAPERCITY_SKILL.md file to your project root. Claude Code reads it automatically, so the agent always knows how to call the API.
Create a separate API key for agent use. If you need to revoke it, your manual access is unaffected.
Store leads (ecommerce data) are instant and cost $0.0039/lead from a cached database. Great for agent workflows that need fast results.
Need Node.js version management? Run: nvm install 20 && nvm use 20. This resolves the most common 'connection closed' MCP errors caused by incompatible Node versions.