MCP Server

The Evomi MCP Server exposes Evomi’s Public API and Scraper API over the Model Context Protocol. AI assistants like Claude can scrape and crawl websites, and manage the proxies on your account — credentials, geo targeting, sticky sessions, usage and balances — from the same conversation.

39 tools by default, 40 with EVOMI_ENABLE_SPENDING=1.

Installation Permalink to 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 mcp 1.x as well as a fresh one that resolves 2.x.

evomi-mcp --version prints the installed version and evomi-mcp --help lists the environment variables it reads. With no arguments it speaks MCP over stdio, which is how an MCP client starts it.

Configuration Permalink to 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. The scraping tools authenticate with the account’s scraper key, which the server reads from the Public API on the first scraping call and holds in memory for the process. That key is never written to disk and never appears in tool output.

Where a specific variable is set, it wins over EVOMI_API_KEY.

The API endpoints can be pointed elsewhere, and default to:

export EVOMI_PUBLIC_BASE_URL="https://api.evomi.com"
export EVOMI_BASE_URL="https://scrape.evomi.com"

Safety Settings Permalink to Safety Settings

Both of these change which tools exist or what they return, so decide on them when you set the server up rather than later:

With EVOMI_HIDE_PROXY_PASSWORDS=1 set:

The two that refuse do so because their entire output is the credential. 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.

Credentials in Tool Output Permalink to Credentials in Tool Output

get_proxy_credentials, build_proxy_connection_string and generate_proxy_list return live proxy passwords, and get_api_access returns a service API key when asked with include_api_key. Those values become part of the conversation with whatever model is connected, and part of whatever that client logs. Every other tool returns balances, endpoints, usage and targeting data only.

Three limits apply either way. The four tools above carry an instruction in their descriptions not to repeat the value back unless it was asked for directly. build_proxy_connection_string and generate_proxy_list return at most 50 entries per call, and refuse a larger request with the limit rather than clamping it. And 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, a ticket or a screenshot — pass runnable_curl_example: true for the form that can be run. The connection strings themselves carry the real password either way.

API keys are read from the environment and sent as headers. They are scrubbed from tool output and error messages.

Usage with Claude Desktop Permalink to 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 (39 Total) Permalink to Available Tools (39 Total)

Thirty-nine tools are registered by default. order_browser_profile brings that to forty, and only when EVOMI_ENABLE_SPENDING=1 is set.

Proxy & Account (9 tools, Evomi Public API, + 1 opt-in) Permalink to Proxy & Account (9 tools, Evomi Public API, + 1 opt-in)

get_proxy_usage covers the four products billed by bandwidth: Premium Residential, Core Residential, Mobile and Datacenter. Static Residential is billed per rented IP instead, so list_proxy_products is where its IPs and their expiry dates are.

Scraping Operations (6 tools) Permalink to Scraping Operations (6 tools)

Config Management (6 tools) Permalink to Config Management (6 tools)

Schema Management (6 tools) Permalink to Schema Management (6 tools)

Storage Management (4 tools) Permalink to Storage Management (4 tools)

Schedule Management (7 tools) Permalink to Schedule Management (7 tools)

Account (1 tool) Permalink to Account (1 tool)

Tool Annotations Permalink to Tool Annotations

Every tool sets all four hints from the MCP spec — readOnlyHint, destructiveHint, idempotentHint and openWorldHint — so a client that gates on them can tell list_configs apart from delete_config. openWorldHint is true for the tools that reach an address the caller chose, and false for those that only talk to Evomi’s own endpoints. readOnlyHint is false for anything that creates, updates, deletes, toggles, rotates or orders. The MUTATING prefix on rotate_proxy_session and order_browser_profile is in the tool description as well, since a description reaches every model where an annotation only reaches a client that reads it.

A failed call comes back as a normal result with isError=True and the reason in the body, not as a transport-level error. Where the Scraper API rejected the request, that body carries the API’s own explanation of the parameter it objected to along with the status, so the next attempt can correct it.

Tool Examples Permalink to Tool Examples

Proxy Connection Strings Permalink to Proxy Connection Strings

// A US residential proxy
{"product": "rp", "countries": ["US"]}

// Berlin, sticky session held for 30 minutes, three strings
{"product": "rp", "countries": ["DE"], "city": "Berlin", "session": "sticky", "lifetime_minutes": 30, "count": 3}

// Datacenter over SOCKS5, in host:port:user:pass format
{"product": "dcp", "countries": ["GB"], "protocol": "socks5", "format": "2"}

// With a curl example that can be pasted and run as it stands
{"product": "rp", "countries": ["US"], "runnable_curl_example": true}

Call list_proxy_targeting_options first whenever a city, region or ISP is involved. Every entry it returns carries an id, which is what the gateway accepts, and a name, which is the display form. Cities, regions and continents take either — North America and north.america reach the same pool. Countries are two-letter ISO 3166-1 alpha-2 codes, so the United Kingdom is GB. An ISP is the one value that has to be the id, since the catalogue abbreviates its label.

A value the gateway does not take is refused with a pointer to what it does, rather than encoded into a string that fails at connect time. City and region targeting take at most one country, and work without one.

Scraping Permalink to 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 Permalink to Crawling

// Basic crawl
{"domain": "example.com", "max_urls": 50}

// With URL filter
{"domain": "example.com", "url_pattern": "/products/", "depth": 3}

Domain Search Permalink to Domain Search

// Find domains
{"query": "best e-commerce sites in Germany", "max_urls": 20, "region": "de-de"}

// Up to 10 queries in one call, max_urls applying to each
{"query": ["online bookstores", "book shops UK"], "max_urls": 50}

Config Management Permalink to 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 Permalink to Scheduling

// Create daily schedule
{"name": "Daily Prices", "config_id": "cfg_abc123", "interval_minutes": 1440, "start_time": "09:00"}

Running the Server Directly Permalink to Running the Server Directly

evomi-mcp
# or
python -m evomi_mcp.server

Credits Permalink to Credits

Scraping, crawling, schema and schedule operations consume Scraper API credits, and what a call costs depends on the mode it runs in and the options it carries. Current rates are in Pricing at a Glance.

Each scraping response carries credits_used and credits_remaining, so the cost of a call is visible in its own result. get_api_access reports the balance on the account.

The proxy tools go through the Public API and spend no Scraper API credits. Reading credentials, usage or targeting options is free, and the traffic you then send through a proxy draws on the product’s data balance, which list_proxy_products reports. order_browser_profile charges that balance directly, with no way to undo the charge, which is why it exists only under EVOMI_ENABLE_SPENDING=1.

Resources Permalink to Resources