Integration Guide
Connect ScraperCity to Google Gemini CLI as an MCP server. Gemini can scrape Apollo leads, extract Google Maps businesses, find business emails, validate deliverability, look up mobile numbers, run skip traces, and export results to CSV - all autonomously from your terminal.
Gemini CLI is Google's open-source AI agent for your terminal. It natively supports the Model Context Protocol (MCP), which lets you connect external tools - like ScraperCity - and call them from natural language prompts. Once the ScraperCity MCP server is registered, Gemini can call any of the 25 available scrapers by name, manage polling, download CSV results, and even write follow-up scripts, all without leaving your terminal.
This makes it practical to run complete B2B data workflows end to end. You can tell Gemini to pull 500 leads from Apollo, find emails for each one, validate deliverability, and save the enriched list - and Gemini handles every API call automatically, using the right ScraperCity endpoint for each step.
ScraperCity tools available through this integration include: Apollo contact scraping, Google Maps business extraction, an email validation API, an email finder, a reverse phone number lookup API, a skip trace API (People Finder), Shopify/WooCommerce store leads, Yelp and Angi listings, Zillow agents, real estate data, property lookups, criminal records, and more - all pay-per-result with no minimums beyond your monthly plan.
Before you configure the MCP server, make sure you have these in place:
Gemini CLI reads MCP server config from ~/.gemini/settings.json for global configuration, or from .gemini/settings.json inside your project directory for project-scoped access. Add the ScraperCity block and restart Gemini CLI.
Log in at app.scrapercity.com/dashboard/api-docs and copy your API key. Keep it handy for the next step.
Open ~/.gemini/settings.json in your editor. If the file does not exist, create it. Add the mcpServers block:
// ~/.gemini/settings.json
{
"mcpServers": {
"scrapercity": {
"command": "npx",
"args": ["-y", "--package", "scrapercity", "scrapercity-mcp"],
"env": {
"SCRAPERCITY_API_KEY": "your_api_key_here"
}
}
}
}You can also use environment variable expansion instead of hardcoding: "SCRAPERCITY_API_KEY": "$SCRAPERCITY_API_KEY" - Gemini CLI will pull the value from your shell environment at runtime.
Restart your Gemini CLI session. Then run the /mcp command to confirm the server connected:
/mcp
# Should show: scrapercity - Ready
# Along with a list of all available ScraperCity toolsIf the server shows as disconnected or the tool count is 0, see the Troubleshooting section below.
Ask Gemini to check your wallet before starting a scrape to avoid failed runs from insufficient balance:
"Check my ScraperCity wallet balance."Gemini calls the free Wallet endpoint and returns your current credit balance. You can top up at app.scrapercity.com if needed.
Every tool below is accessible through the Gemini CLI integration. All plans include access to all 25 scrapers. The Lead Database query requires the $649/mo plan.
| Tool | What It Returns | Cost | Delivery |
|---|---|---|---|
| Apollo Scraper | B2B contacts by title, industry, location | $0.0039/lead | 11-48+ hrs |
| Google Maps | Local businesses with phones, emails, reviews | $0.01/place | 5-30 min |
| Email Validator | Deliverability, catch-all, MX record checks | $0.0036/email | 1-10 min |
| Email Finder | Business email from name + company domain | $0.05/contact | 1-10 min |
| Mobile Finder | Phone numbers from LinkedIn or email | $0.25/input | 1-5 min |
| People Finder (Skip Trace) | Skip trace by name, email, phone, or address | $0.02/result | 2-10 min |
| Store Leads | Shopify/WooCommerce stores with contacts | $0.0039/lead | Instant |
| BuiltWith | All sites using a specific technology | $4.99/search | 1-5 min |
| Property Lookup | Property data + owner contact info | $0.15/address | 2-10 min |
| Lead Database | 3M+ B2B contacts, instant query ($649 plan) | See plan | Instant |
| Yelp / Angi / Zillow | Local business and service provider listings | $0.01/listing | 5-15 min |
| Criminal Records | Background check by name | $1.00 if found | 2-5 min |
“Scrape Google Maps for all dentists in Houston, TX. Download the results and count how many have a website listed.”
Gemini triggers the Maps scraper, polls until done, downloads the CSV, then analyzes it inline.
“I have a file called prospects.csv with a company_domain column. For each domain, find the CEO or founder email using ScraperCity. Save the enriched list.”
Gemini reads the CSV, loops through domains with the email finder endpoint, and merges results back.
“Check my ScraperCity wallet balance. If I have at least $10, run an Apollo scrape for marketing managers at fintech companies in London.”
Gemini checks the wallet first, then conditionally triggers the scrape to avoid insufficient-balance errors.
“Validate all the emails in leads.csv and create two files: valid-emails.csv and invalid-emails.csv”
Gemini feeds emails to the validation endpoint in batches, then sorts results by deliverability status.
“Run a skip trace on these five contacts. I have their names and last known addresses in a list.”
Gemini calls the People Finder endpoint for each contact, polls for results, and returns phone numbers and current address data.
“Find mobile phone numbers for this list of LinkedIn profile URLs and save them as phone-list.csv.”
Gemini passes each URL to the Mobile Finder endpoint, handles rate limits across calls, and writes a clean output file.
“Scrape all Shopify stores selling yoga equipment. Find the owner email for each store and export to a CSV.”
Gemini uses Store Leads to find matching stores, then loops through each result with the Email Finder to enrich the dataset.
The real power of connecting ScraperCity to Gemini is chaining multiple endpoints together in a single conversation. Here are the most common multi-step workflows users run:
The same MCP server works anywhere Google exposes Gemini with tool support:
Agent mode in VS Code. Add the mcpServers block to your Gemini settings JSON. Gemini Code Assist automatically decides when to call each tool.
Add to .idx/mcp.json or .gemini/settings.json in your workspace. Useful for enriching leads inside Firebase-backed app projects.
Python and JS SDKs support MCP tool sessions natively. Pass your ScraperCity MCP config to the session and call tools programmatically.
Problem: scrapercity shows as DISCONNECTED in /mcp
Fix: Check that your API key is correctly pasted in settings.json with no extra spaces or quotes. Verify npx is on your PATH by running npx --version in your terminal. Restart Gemini CLI completely after any settings.json change.
Problem: /mcp shows 0 tools for scrapercity
Fix: The MCP server process started but could not authenticate. Open a terminal and run: SCRAPERCITY_API_KEY=your_key npx -y --package scrapercity scrapercity-mcp to check for error output directly. A 401 response means your API key is invalid or expired.
Problem: Apollo scrape never returns results
Fix: Apollo scrapes take 11-48+ hours by design. Do not poll in a loop during an active Gemini session. Instead, ask Gemini to save the run ID and set up a webhook at app.scrapercity.com/dashboard/webhooks. When the scrape finishes, retrieve the run ID and ask Gemini to download the results.
Problem: Insufficient balance error on a scrape
Fix: Each endpoint deducts credits per result. Ask Gemini to check your wallet balance first: 'Check my ScraperCity wallet balance.' If the balance is too low, top up at app.scrapercity.com before retrying the job.
Problem: Duplicate request blocked (30-second window)
Fix: ScraperCity blocks identical requests submitted within 30 seconds of each other as duplicate protection. If Gemini retried a failed request too quickly, wait 30 seconds and try again. If the retry loop is in an automated script, add a delay between attempts.
Problem: settings.json changes not taking effect
Fix: Gemini CLI reads settings.json at startup. You must fully exit and relaunch the CLI after any edit. Use /chat save before restarting if you want to preserve your conversation context, then /chat resume after relaunch.
Problem: API key exposed in settings.json
Fix: Use environment variable expansion instead of hardcoding. In settings.json, set "SCRAPERCITY_API_KEY": "$SCRAPERCITY_API_KEY" and export the variable in your shell profile (~/.zshrc or ~/.bashrc). Gemini CLI resolves it at runtime without storing the value in the file.
Run /mcp after setup to confirm ScraperCity shows as connected. If it shows 0 tools, check your API key and restart the CLI.
Apollo scrapes take 11-48+ hours to deliver. Have Gemini set up a webhook at app.scrapercity.com/dashboard/webhooks instead of polling in a loop.
Gemini CLI supports project-level config at .gemini/settings.json. Scope your ScraperCity API key to specific projects this way rather than using your global config for every project.
For long-running scrapes, ask Gemini to write a standalone polling script you can run on a cron. This decouples the scrape from your active CLI session so you do not need to keep the terminal open.
Use environment variable expansion in settings.json - set SCRAPERCITY_API_KEY to $SCRAPERCITY_API_KEY and export it in your shell profile. This keeps your key out of the file on disk.
When processing large CSV files with email validation or phone lookup, ask Gemini to work in batches of 50-100 rows and save progress checkpoints. This prevents losing work if the session is interrupted.
The Lead Database endpoint (instant B2B queries against 3M+ contacts) requires the $649/mo plan. If you get an access error on that endpoint, check your plan tier first before troubleshooting the MCP config.