Skip to main content
Glama
Evomi MCP Server

Evomi MCP Server

Official
by evomi

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-mcp

Needs 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

EVOMI_PUBLIC_API_KEY

Public API key

proxy credentials, usage, targeting, sessions — and, indirectly, everything else

EVOMI_SCRAPER_API_KEY

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

EVOMI_API_KEY

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 balance

Credentials 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

get_proxy_credentials

Masked. The username, gateway, ports and balance are unchanged

get_api_access

Masked, even when include_api_key: true is passed explicitly

build_proxy_connection_string

Refuses, naming the variable

generate_proxy_list

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

list_proxy_products

Products on the account with endpoints, ports, balance and username

No

get_proxy_credentials

Proxy username and password for one product

Yes

build_proxy_connection_string

Connection strings with geo targeting, sessions and expert filters, plus a curl check

Yes

generate_proxy_list

Bulk proxy list (up to 50 per call) from the Public API generator

Yes

get_proxy_usage

Bandwidth used over 24h / 3d / 7d, total and per bucket

No

list_proxy_targeting_options

Searchable countries, regions, cities, ISPs and continents per product, each with the id the gateway accepts

No

rotate_proxy_session

Mutating — force a sticky session onto a new exit IP

No

get_api_access

Scraper and Browser access, credits, concurrency and endpoints (keys masked by default)

Only on request

list_browser_profiles

Saved browser fingerprint profiles

No

order_browser_profile

Mutating, spends money — orders a browser fingerprint profile, charged against the account's data balance. Only registered when EVOMI_ENABLE_SPENDING=1

No

Scraping Operations (6 tools)

Tool

Description

scrape_url

Scrape a single URL with configurable options

crawl_website

Crawl a website to discover and scrape multiple pages

map_website

Discover URLs from a website

search_domains

Find domains by searching the web

agent_request

AI-powered conversational scraping assistant

get_task_status

Check the status of an async task

Config Management (6 tools)

Tool

Description

list_configs

List all saved scrape configurations

create_config

Create a new scrape configuration

get_config

Get a saved scrape configuration by ID

update_config

Update an existing scrape configuration

delete_config

Delete a scrape configuration

generate_config

Generate a scrape config from natural language using AI

Schema Management (6 tools)

Tool

Description

list_schemas

List all saved extraction schemas

create_schema

Create a new extraction schema

get_schema

Get a saved extraction schema by ID

update_schema

Update an existing extraction schema

delete_schema

Delete an extraction schema

get_schema_status

Get the test status of an extraction schema

Storage Management (4 tools)

Tool

Description

list_storage_configs

List all storage configurations

create_storage_config

Create a new storage configuration

update_storage_config

Update an existing storage configuration

delete_storage_config

Delete a storage configuration

Schedule Management (7 tools)

Tool

Description

list_schedules

List all scheduled scrape jobs

create_schedule

Create a new scheduled scrape job

get_schedule

Get a scheduled job by ID

update_schedule

Update an existing scheduled job

delete_schedule

Delete a scheduled job

toggle_schedule

Toggle a scheduled job active/inactive

list_schedule_runs

Get execution history for a scheduled job

Account (1 tool)

Tool

Description

get_account_info

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}
// 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.server

Tests

pytest

The 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.

License

MIT — see LICENSE.

Available Tools

39 tools
agent_requestA
Destructive

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_stringA
Read-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_websiteA
Read-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_configB
DestructiveIdempotent

Delete a scrape configuration.

Inputs: config_id (required).

delete_scheduleB
DestructiveIdempotent

Delete a scheduled job.

Inputs: schedule_id (required).

delete_schemaC
DestructiveIdempotent

Delete an extraction schema.

Inputs: scheme_id (required).

delete_storage_configC
DestructiveIdempotent

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_listA
Read-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_infoA
Read-onlyIdempotent

Get account information including credit balance and user details.

Inputs: no named parameters.

get_api_accessA
Read-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_configA
Read-onlyIdempotent

Get a saved scrape configuration by ID.

Inputs: config_id (required).

get_proxy_credentialsA
Read-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_usageA
Read-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_scheduleA
Read-onlyIdempotent

Get a scheduled job by ID.

Inputs: schedule_id (required).

get_schemaA
Read-onlyIdempotent

Get a saved extraction schema by ID.

Inputs: scheme_id (required).

get_schema_statusC
Read-onlyIdempotent

Get the test status of an extraction schema.

Inputs: scheme_id (required).

get_task_statusC
Read-onlyIdempotent

Check the status of an async task (scrape, crawl, or map).

Inputs: task_id (required), task_type.

list_browser_profilesA
Read-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_configsC
Read-onlyIdempotent

List all saved scrape configurations.

Inputs: page, sort_by, per_page, sort_order.

list_proxy_productsA
Read-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_optionsA
Read-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_runsA
Read-onlyIdempotent

Get execution history for a scheduled job.

Inputs: schedule_id (required), page, per_page.

list_schedulesC
Read-onlyIdempotent

List all scheduled scrape jobs.

Inputs: page, per_page, active_only.

list_schemasC
Read-onlyIdempotent

List all saved extraction schemas.

Inputs: page, sort_by, per_page, sort_order.

list_storage_configsA
Read-onlyIdempotent

List all storage configurations (S3, GCS, Azure Blob).

Inputs: no named parameters.

map_websiteB
Read-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_sessionA
Destructive

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_urlA
Read-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_domainsA
Read-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_configC
DestructiveIdempotent

Update an existing scrape configuration.

Inputs: config_id (required), name, config.

update_scheduleC
DestructiveIdempotent

Update an existing scheduled job.

Inputs: schedule_id (required), name, config_id, stop_on_error, +1 more.

update_schemaC
DestructiveIdempotent

Update an existing extraction schema.

Inputs: name (required), config (required), scheme_id (required), fix, +2 more.

update_storage_configC
DestructiveIdempotent

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

    B3.1/5.0

    Scored across 39 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers