Evomi MCP Server
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Evomi MCP Server Scrape example.com from US"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Evomi MCP Server
A Model Context Protocol (MCP) server for Evomi's proxy and web scraping APIs. It gives AI assistants like Claude direct access to a proxy account — credentials, connection strings, geo targeting, usage, session rotation — alongside a full scraping toolkit for crawling sites and extracting structured data.
39 tools by default, 40 with EVOMI_ENABLE_SPENDING=1.
Features
Proxy & account management
Proxy Credentials - Username and password for each product on the account
Connection Strings - Geo-targeted, session-pinned strings, with a curl command to check them
Bulk Proxy Lists - Up to 50 endpoints per call
Geo Targeting - Search the countries, regions, cities and ISPs a product actually offers
Usage & Balance - Bandwidth over 24h, 3d and 7d, in total and per bucket
Session Control - Rotate a sticky session onto a new exit IP
Browser Profiles - List saved fingerprint profiles, and order more behind an opt-in
Service Access - Scraper and Browser credits, concurrency and endpoints
Web scraping
Single Page Scraping - Scrape any URL with automatic JavaScript detection
Website Crawling - Multi-page crawling with depth control
URL Discovery - Find URLs via sitemaps, CommonCrawl, or in-site crawling
Domain Search - Find domains by searching the web
AI-Powered Extraction - Use AI to extract structured data from pages
Conversational Agent - Natural language interface for scraping tasks
Config Management - Save and reuse scraping configurations
Schema Management - Define and test extraction schemas
Storage Configuration - Manage cloud storage for scraped data
Scheduled Jobs - Automate scraping on a schedule
Related MCP server: krwl3r
Installation
pip install evomi-mcpNeeds Python 3.10 or newer. The server runs on both major versions of the mcp
SDK (>=1.8.0,<3), so it installs into an environment already pinned to 1.x as
well as a fresh one that resolves 2.x.
Run evomi-mcp --help for the environment variables it reads, or evomi-mcp --version for the installed version. With no arguments it speaks MCP over
stdio, which is how an MCP client starts it.
Configuration
One credential is enough:
export EVOMI_PUBLIC_API_KEY="your-public-api-key"Take it from Settings > API for a personal account, or Settings > Team for a team one. It authenticates the proxy and account tools directly, and the scraping tools authenticate with the account's scraper key, which the server reads from the Public API on the first scraping call and keeps in memory for the process. It is never written to disk and never appears in tool output.
Variable | Key | Used by |
| Public API key | proxy credentials, usage, targeting, sessions — and, indirectly, everything else |
| Scraper API key, from the same page | scraping, crawling, configs, schemas, schedules. Optional: set it to pin a specific key, and no lookup is made |
| Fallback for either of the above | both, when the specific variable is unset |
Where a specific variable is set it wins over EVOMI_API_KEY. Setting a scraper
key alone works too, and the proxy and account tools then need
EVOMI_PUBLIC_API_KEY as well, since one key cannot serve both APIs.
Optional settings:
export EVOMI_BASE_URL="https://scrape.evomi.com" # scraper API, default
export EVOMI_PUBLIC_BASE_URL="https://api.evomi.com" # public API, default
export EVOMI_HIDE_PROXY_PASSWORDS=1 # mask every proxy password and service API key
export EVOMI_ENABLE_SPENDING=1 # register the tools that spend account balanceCredentials in tool output
get_proxy_credentials, build_proxy_connection_string and generate_proxy_list
return live proxy passwords, which is what they are for, and get_api_access
returns a service API key when asked with include_api_key. Every other tool
returns balances, endpoints, usage and targeting data only.
Four things bound that. Those four tools carry an instruction in their
descriptions not to repeat the value back unless it was asked for directly — the
MCP spec has no annotation for a sensitive result, so the description is the only
channel that reaches the model. generate_proxy_list and
build_proxy_connection_string return at most 50 entries per call, well under
the 500 the Public API allows, and refuse a larger request rather than clamping
it. The curl_example that comes with a connection string has its password
masked, since it is the field most likely to be pasted into a terminal or a
ticket; pass runnable_curl_example: true for the form that can be run. And
EVOMI_HIDE_PROXY_PASSWORDS=1 turns disclosure off entirely:
Tool | With the flag set |
| Masked. The username, gateway, ports and balance are unchanged |
| Masked, even when |
| Refuses, naming the variable |
| Refuses before the API is called, so the bulk credentials are never minted |
every other tool | Unchanged — none of them returns a credential |
The two that refuse do so because their entire output is the credential: a
connection string with a masked password cannot connect. The refusal points at
list_proxy_products and list_proxy_targeting_options, which give the gateway
hostname, ports and targeting values with no credential in them, and the
descriptions the model sees change too.
EVOMI_ENABLE_SPENDING=1 is the opposite, an opt-in for the one tool that costs
money. Without it order_browser_profile is not registered at all, so the
connected model never sees it.
Tool annotations
Every tool sets all four of the MCP spec's hints. destructiveHint and
openWorldHint default to true, so a tool that omits them advertises itself
as potentially destructive and as reaching an unbounded external world.
openWorldHint is true for the tools that reach an address the caller chose
(scrape_url, crawl_website, map_website, search_domains, agent_request,
and the schema and config tools that validate against the page they describe),
and false for everything that only talks to Evomi's own endpoints.
readOnlyHint is false for the tools that create, update, delete, toggle, rotate
or order something. The MUTATING prefix on rotate_proxy_session and
order_browser_profile is in the description as well, because the description
reaches every model where an annotation only reaches a client that reads it.
Usage with Claude Desktop
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"evomi": {
"command": "evomi-mcp",
"env": {
"EVOMI_PUBLIC_API_KEY": "your-public-api-key"
}
}
}
}Or if installed from source:
{
"mcpServers": {
"evomi": {
"command": "python",
"args": ["-m", "evomi_mcp.server"],
"env": {
"EVOMI_PUBLIC_API_KEY": "your-public-api-key"
}
}
}
}Available Tools
Proxy & Account (9 tools, Evomi Public API, + 1 opt-in)
Tool | Description | Returns credentials |
| Products on the account with endpoints, ports, balance and username | No |
| Proxy username and password for one product | Yes |
| Connection strings with geo targeting, sessions and expert filters, plus a curl check | Yes |
| Bulk proxy list (up to 50 per call) from the Public API generator | Yes |
| Bandwidth used over 24h / 3d / 7d, total and per bucket | No |
| Searchable countries, regions, cities, ISPs and continents per product, each with the | No |
| Mutating — force a sticky session onto a new exit IP | No |
| Scraper and Browser access, credits, concurrency and endpoints (keys masked by default) | Only on request |
| Saved browser fingerprint profiles | No |
| Mutating, spends money — orders a browser fingerprint profile, charged against the account's data balance. Only registered when | No |
Scraping Operations (6 tools)
Tool | Description |
| Scrape a single URL with configurable options |
| Crawl a website to discover and scrape multiple pages |
| Discover URLs from a website |
| Find domains by searching the web |
| AI-powered conversational scraping assistant |
| Check the status of an async task |
Config Management (6 tools)
Tool | Description |
| List all saved scrape configurations |
| Create a new scrape configuration |
| Get a saved scrape configuration by ID |
| Update an existing scrape configuration |
| Delete a scrape configuration |
| Generate a scrape config from natural language using AI |
Schema Management (6 tools)
Tool | Description |
| List all saved extraction schemas |
| Create a new extraction schema |
| Get a saved extraction schema by ID |
| Update an existing extraction schema |
| Delete an extraction schema |
| Get the test status of an extraction schema |
Storage Management (4 tools)
Tool | Description |
| List all storage configurations |
| Create a new storage configuration |
| Update an existing storage configuration |
| Delete a storage configuration |
Schedule Management (7 tools)
Tool | Description |
| List all scheduled scrape jobs |
| Create a new scheduled scrape job |
| Get a scheduled job by ID |
| Update an existing scheduled job |
| Delete a scheduled job |
| Toggle a scheduled job active/inactive |
| Get execution history for a scheduled job |
Account (1 tool)
Tool | Description |
| Get account information including credit balance |
Tool Examples
Scraping
// Basic scrape
{"url": "https://example.com"}
// AI extraction
{"url": "https://example.com/products", "ai_enhance": true, "ai_prompt": "Extract product names and prices"}
// Browser mode with actions
{"url": "https://example.com", "mode": "browser", "js_instructions": [{"click": ".accept-cookies"}, {"wait": 1000}]}Crawling
// Basic crawl
{"domain": "example.com", "max_urls": 50}
// With URL filter
{"domain": "example.com", "url_pattern": "/products/", "depth": 3}Domain Search
// Find domains
{"query": "best e-commerce sites for electronics", "max_urls": 20, "region": "us-en"}
// Up to 10 queries in one call, max_urls applying to each
{"query": ["online bookstores", "book shops UK"], "max_urls": 50}Config Management
// Create config
{"name": "Product Scraper", "config": {"mode": "browser", "output": "markdown"}}
// Generate config with AI
{"name": "Amazon Scraper", "prompt": "Scrape product title, price, and reviews from Amazon"}Scheduling
// Create daily schedule
{"name": "Daily Prices", "config_id": "cfg_abc123", "interval_minutes": 1440, "start_time": "09:00"}Credits
Scraping operations consume credits, and what a call costs depends on the mode it
runs in and the options it carries. The current rates are at
docs.evomi.com; get_api_access reports the balance on
the account.
Each scraping response carries credits_used and credits_remaining, so the
cost of a call is visible in its own result.
Development
Setup
pip install -e ".[dev]"Running the Server Directly
evomi-mcp
# or
python -m evomi_mcp.serverTests
pytestThe suite runs against both mcp majors, and CI runs it on each of them across
the supported Python versions.
Releasing
The version is declared in both pyproject.toml and src/evomi_mcp/__init__.py,
and CI fails if they disagree. Publishing a GitHub Release tagged vX.Y.Z builds
the artifacts, runs the suite against the built wheel and uploads to PyPI over
Trusted Publishing, so there is no token anywhere.
Links
License
MIT — see LICENSE.
Available Tools
39 toolsagent_requestADestructive
AI-powered conversational assistant that can do ANY Evomi operation. Ask it to: create configs, run scrapes, discover URLs, schedule jobs, check account info, and more. Examples: 'Scrape example.com and figure out what to extract', 'Create a config for Amazon products', 'Schedule my config to run daily', 'How many credits do I have?'
Inputs: message (required).
build_proxy_connection_stringARead-only
Build ready-to-use Evomi proxy connection strings with geo targeting, sticky sessions and expert filters encoded into the password, plus a curl command to verify them. This is the tool to use when someone asks for 'a US residential proxy', 'proxies for Berlin', 'a sticky session', or how to configure a proxy in code. Fetches the account's own credentials, so the output CONTAINS THE PROXY PASSWORD. Validates the targeting against the chosen product and explains any unsupported combination instead of returning a string that would fail at connect time. Read-only. SECRET HANDLING: the password inside each connection string is a live credential. Use it to carry out the task — write it into the config, command or code the user asked for — and do not repeat the value back in your reply. Show it only if the user explicitly asks to see it.
Inputs: product (required), asn, isp, udp, +24 more.
crawl_websiteARead-only
Crawl a website to discover and scrape multiple pages. Follows links up to specified depth. The scraper_config can include a config_id to use saved settings, or full scraping options.
Inputs: domain (required), depth, max_urls, async_mode, +2 more.
create_configB
Create a new scrape configuration for reuse.
Inputs: name (required), config (required).
create_scheduleC
Create a new scheduled scrape job that runs at regular intervals.
Inputs: name (required), config_id (required), interval_minutes (required), start_time, +1 more.
create_schemaC
Create a new extraction schema for structured data extraction.
Inputs: name (required), config (required), fix, test, +1 more.
create_storage_configC
Create a new storage configuration for saving scraped data.
Inputs: name (required), config (required), storage_type (required), set_as_default.
delete_configBDestructiveIdempotent
Delete a scrape configuration.
Inputs: config_id (required).
delete_scheduleBDestructiveIdempotent
Delete a scheduled job.
Inputs: schedule_id (required).
delete_schemaCDestructiveIdempotent
Delete an extraction schema.
Inputs: scheme_id (required).
delete_storage_configCDestructiveIdempotent
Delete a storage configuration.
Inputs: storage_id (required).
generate_configC
Generate a scrape config from a natural language prompt using AI.
Inputs: name (required), prompt (required).
generate_proxy_listARead-only
Generate a bulk list of Evomi proxy strings server-side via the Public API (up to 50 per call), for pasting into tools that take a proxy list file. Output CONTAINS PROXY PASSWORDS. Supports only country/city/region/ISP targeting, sessions and ad blocking — for zip, ASN, pool mode or expert filters use build_proxy_connection_string instead. Fails if the product has no data balance. Read-only. SECRET HANDLING: the password inside each returned proxy line is a live credential. Use it to carry out the task — write it into the config, command or code the user asked for — and do not repeat the value back in your reply. Show it only if the user explicitly asks to see it.
Inputs: product (required), isp, city, amount, +8 more.
get_account_infoARead-onlyIdempotent
Get account information including credit balance and user details.
Inputs: no named parameters.
get_api_accessARead-onlyIdempotent
Check this account's access to Evomi's Scraper API and Scraping Browser: whether it is enabled, remaining credits, concurrency limit, max session length, and the endpoint URL to connect to. The per-service API keys are MASKED unless include_api_key is set to true. Use this to find out why a scrape failed for lack of credits, or to retrieve the scraper key needed to configure EVOMI_SCRAPER_API_KEY. Read-only. SECRET HANDLING: the API key returned when include_api_key is true is a live credential. Use it to carry out the task — write it into the config, command or code the user asked for — and do not repeat the value back in your reply. Show it only if the user explicitly asks to see it.
Inputs: service, include_api_key.
get_configARead-onlyIdempotent
Get a saved scrape configuration by ID.
Inputs: config_id (required).
get_proxy_credentialsARead-onlyIdempotent
Get the proxy username and PLAINTEXT PASSWORD for one Evomi proxy product, along with its gateway hostname, ports and remaining balance. Returns a live credential that grants paid proxy access — prefer build_proxy_connection_string when the user just wants something to paste into a client. Read-only: it does not rotate or change the password. SECRET HANDLING: the password is a live credential. Use it to carry out the task — write it into the config, command or code the user asked for — and do not repeat the value back in your reply. Show it only if the user explicitly asks to see it.
Inputs: product (required).
get_proxy_usageARead-onlyIdempotent
Get bandwidth used for one Evomi proxy product over the last 24 hours, 3 days or 7 days, as a period total plus per-bucket figures — the same numbers as the dashboard usage chart. Use for 'how much traffic have I used', spend checks and usage trends. For how much balance is LEFT, use list_proxy_products instead. Returns no credentials. Read-only.
Inputs: product (required), period, max_buckets, include_buckets.
get_scheduleARead-onlyIdempotent
Get a scheduled job by ID.
Inputs: schedule_id (required).
get_schemaARead-onlyIdempotent
Get a saved extraction schema by ID.
Inputs: scheme_id (required).
get_schema_statusCRead-onlyIdempotent
Get the test status of an extraction schema.
Inputs: scheme_id (required).
get_task_statusCRead-onlyIdempotent
Check the status of an async task (scrape, crawl, or map).
Inputs: task_id (required), task_type.
list_browser_profilesARead-onlyIdempotent
List the saved browser fingerprint profiles on this account (id, OS, browser, version, creation date). Use to find a profile id before launching a browser session. Does not return the fingerprint payload itself and returns no credentials. Read-only.
Inputs: no named parameters.
list_configsCRead-onlyIdempotent
List all saved scrape configurations.
Inputs: page, sort_by, per_page, sort_order.
list_proxy_productsARead-onlyIdempotent
List the Evomi proxy products on this account with their gateway hostname, HTTP/SOCKS5 ports, remaining data balance, and proxy username. Products: rp = Premium Residential, rpc = Core Residential, dcp = Datacenter (Shared), mp = Mobile, static_residential = Static Residential. Returns NO proxy passwords — use get_proxy_credentials or build_proxy_connection_string for those. Call this first to see what the account actually has balance on.
Inputs: no named parameters.
list_proxy_targeting_optionsARead-onlyIdempotent
Look up which countries, regions, cities, ISPs or continents can be targeted on a given Evomi proxy product, with an optional search filter. Call this before build_proxy_connection_string whenever a city, region or ISP is involved. Every entry gives an 'id' and a 'name': the 'id' is what the gateway accepts and what to pass back, the 'name' is the display form. The full catalogue is large, so results are filtered and capped. Returns no credentials. Read-only.
Inputs: product (required), kind, limit, search.
list_schedule_runsARead-onlyIdempotent
Get execution history for a scheduled job.
Inputs: schedule_id (required), page, per_page.
list_schedulesCRead-onlyIdempotent
List all scheduled scrape jobs.
Inputs: page, per_page, active_only.
list_schemasCRead-onlyIdempotent
List all saved extraction schemas.
Inputs: page, sort_by, per_page, sort_order.
list_storage_configsARead-onlyIdempotent
List all storage configurations (S3, GCS, Azure Blob).
Inputs: no named parameters.
map_websiteBRead-only
Discover URLs from a website using sitemaps, CommonCrawl, or in-site crawling.
Inputs: domain (required), sources, max_urls, async_mode, +2 more.
rotate_proxy_sessionADestructive
MUTATING: force an existing Evomi sticky session onto a new exit IP. The current connection is dropped immediately and the old IP is released; the session id and credentials stay the same. Use when a session's IP has been blocked. Only call when the user asks to rotate or change IP — it disrupts anything currently using that session. Returns no credentials.
Inputs: product (required), session_id (required).
scrape_urlARead-only
Scrape a single URL. Modes: request (fast), browser (JS), auto (detect). Output: html, markdown, screenshot, pdf. Use ai_enhance with ai_prompt for AI extraction.
Inputs: url (required), pdf, mode, device, +26 more.
search_domainsARead-only
Find domains by searching the web. Use this to discover websites when you don't know specific domains. Returns list of domains with URLs and titles.
Inputs: query (required), region, max_urls.
toggle_scheduleA
Toggle a scheduled job active/inactive.
Inputs: schedule_id (required).
update_configCDestructiveIdempotent
Update an existing scrape configuration.
Inputs: config_id (required), name, config.
update_scheduleCDestructiveIdempotent
Update an existing scheduled job.
Inputs: schedule_id (required), name, config_id, stop_on_error, +1 more.
update_schemaCDestructiveIdempotent
Update an existing extraction schema.
Inputs: name (required), config (required), scheme_id (required), fix, +2 more.
update_storage_configCDestructiveIdempotent
Update an existing storage configuration.
Inputs: storage_id (required), name, config, set_as_default.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Most tools are organized by resource and have distinct purposes, but agent_request intentionally overlaps with every other operation by being able to 'do ANY Evomi operation'. The proxy credential/connection-string tools also overlap and rely heavily on detailed descriptions to avoid misselection.
The vast majority of tools follow a consistent verb_noun snake_case pattern: list_configs, create_schedule, get_proxy_credentials, rotate_proxy_session. The one clear outlier is agent_request, which is noun-like rather than an imperative verb, preventing a perfect score.
With 39 tools, the server is well past the 25-tool threshold for an agent-friendly surface. The count is inflated by multiple parallel CRUD families plus several proxy-related generators and builders, making tool selection harder even though the domains are related.
Core scraping and proxy lifecycle coverage is strong: scrape/crawl/map, configs, schemas, schedules, proxies, and account info are all represented. However, storage configs lack a get_storage_config, browser profiles only have a list operation, and async tasks have no cancellation or history listing, so some workflows dead-end.
Maintenance
Related MCP Connectors
Web scraping MCP server — scrape, extract structured data, screenshot any site with anti-bot bypass.
Zenrows MCP server: Fetch, Extract, Batch, and Browser Sessions for AI agents
All HasData scraping tools in one MCP server: Google, TikTok, Instagram, maps, e-commerce and more.
Web scraping, extraction and search for AI agents. Hosted MCP with workspace API keys.
Related MCP Servers
- AlicenseBqualityCmaintenanceMCP server for the Spider web crawling and scraping API, enabling AI agents to crawl, scrape, search, and extract web data.132MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for web scraping and browser automation, enabling AI agents to extract clean, token-efficient content from web pages.1MIT
- AlicenseAqualityCmaintenanceMCP server providing tools for web scraping, browser automation, computer vision, audio transcription, and RAG via API.979 PyPIMIT

aethyn-browser-mcpofficial
AlicenseAqualityDmaintenanceAn MCP server enabling AI agents to drive a real browser through residential proxies with per-task geo (country/city) and sticky identity, all chosen at call time.1066 npm4MIT