MCP Server
The Evomi MCP Server
Point Claude, Cursor, or anything else that speaks the Model Context Protocol at your Evomi account, and it can collect data the same way you would from the dashboard. Scrape a page. Pick a country. Hold a session. Check what it spent.
pip install evomi-mcp
- Python 3.10 or newer
- MIT licensed
- Runs over stdio
39 tools in 7 groups
- Proxy & account9
- Scraping6
- Configs6
- Extraction schemas6
- Storage4
- Schedules7
- Account1
Capabilities
What your agent can actually do
Every other MCP server in this market lets a model read a page. This one also lets it hold the connection.
A scrape that gets blocked is not a scrape, and what decides that is the connection underneath it: which address the request left from, whether the last five requests came from that same address, which country the site thinks you are in. Those are the controls this server also exposes. An agent that can only ask for a page has to hope; one that can pick an exit country and hold a session can fix the problem itself and try again.
Read the web
scrape_url takes a URL and returns the page as markdown, HTML, a screenshot or a PDF, with JavaScript rendered if the page needs it. crawl_website walks a site; map_website lists what is there without fetching it. search_domains finds sites matching a description rather than a URL you already knew, and agent_request takes a plain-language brief when you would rather not specify the shape of the answer.
All of it runs on the Scraper API, with rendering, retries and rotation handled server-side. Pages that need a full browser can go through the Scraping Browser instead.
Hold the connection
list_proxy_targeting_options returns the actual catalogue — countries, regions, cities, ISPs, continents — each with the identifier the gateway accepts and the name a human reads. build_proxy_connection_string turns a choice from it into a working connection string: residential in the US, or Berlin on a sticky session, or datacenter over SOCKS5. rotate_proxy_session forces a sticky session onto a new exit IP when the current one has stopped working.
So an agent that gets a geo-blocked response does not report failure. It reads the catalogue, picks a country, rebuilds the connection and retries — inside the same conversation, without you writing the retry logic.
Watch what it spends
get_proxy_usage reports bandwidth over the last 24 hours, 3 days and 7 days, per product. list_proxy_products gives the balance on each one, with the endpoints and ports. get_api_access reports Scraper API credits and concurrency, and get_account_info gives the account balance.
An agent spending money on your behalf is a reasonable thing to be nervous about, so you can ask what it has used in the same conversation where it used it. Every scraping response also reports its own cost inline.
Setup
Install it in three steps
One package, one credential, one line in your client's configuration.
- Step 1
Install the package
pip install evomi-mcpRun pip install evomi-mcp. It needs Python 3.10 or newer, and it installs against either major version of the mcp SDK — so a fresh environment and one already pinned to 1.x both work.
- Step 2
Add your API key
EVOMI_PUBLIC_API_KEY=your-public-api-keyOne credential covers everything. Take your Public API key from Settings then API in the dashboard, set it as EVOMI_PUBLIC_API_KEY, and the scraping tools resolve the account’s Scraper API key from it on their own.
- Step 3
Point your client at it
evomi-mcpAdd evomi-mcp as a command in your client’s MCP configuration, with that variable in its environment block. Then ask for something, and approve the first tool call when the client asks.
The configuration block for each client is kept next to the server rather than restated here, in the MCP server documentation. Your key is on the API settings page.
Clients
Works with the client you use
The server is an ordinary local MCP server, so it does not know or care which client started it. That is the point of the protocol.
- Claude Desktop
- Claude Code
- Cursor
- VS Code
- Windsurf
- Zed
- Cline
- A client you wrote yourself
The one requirement is that the client can launch a local process: the package speaks stdio, so something on your machine has to start it. A client that only accepts a remote URL cannot reach it.
Already building in n8n? Evomi ships an n8n integration too, and the two compose — the MCP server for the parts where a model decides what to collect, the n8n nodes for the parts where the workflow already knows.
Tools
39 tools, in 7 groups
Competitors publish two to five tools, or sixty that are all variants of “fetch this URL”. A specific count is what makes the claim checkable.
| Group | Tools | What it covers |
|---|---|---|
| Proxy & account | 9 | Credentials, connection strings, bulk lists, usage, the targeting catalogue, session rotation, service access and browser profiles |
| Scraping | 6 | Scrape, crawl, map, domain search, a plain-language agent, and async task status |
| Configs | 6 | Save, read, update, delete and AI-generate reusable scrape configurations |
| Extraction schemas | 6 | Define the shape you want data returned in, and test it before you rely on it |
| Storage | 4 | Where results get delivered |
| Schedules | 7 | Recurring jobs, their on/off state and their run history |
| Account | 1 | The account balance |
Every tool sets all four of the protocol’s hints, so a client that gates on annotations can tell list_configs apart from delete_config without reading a word of the description.
- readOnlyHint
- False on anything that creates, updates, deletes, toggles, rotates or orders.
- destructiveHint
- Defaults to true, so a tool that omits it advertises itself as potentially destructive.
- idempotentHint
- Set on every tool rather than left to the client to guess.
- openWorldHint
- Also defaults to true, and separates the tools that reach an address you chose from the ones that only ever talk to Evomi.
Every tool, with its arguments and its annotations, is listed in the MCP server documentation.
Architecture
What runs on your machine
A local process your client starts, talking to two Evomi APIs over HTTPS. Nothing in between.
The package is the whole server, which is the property worth knowing if you are the one signing off on where the credentials go.
Where a job outlives a single call the handle is explicit rather than hidden in the transport. crawl_website returns a task id and get_task_status takes it back as an ordinary argument, so the model can see the handle and reason about it instead of depending on a session it cannot inspect.
The package, in short
- Install
- pip install evomi-mcp, on Python 3.10 or newer
- Credentials
- Read from environment variables. The scraper key is resolved in memory for the process, never written to disk
- SDK
- Runs on both major versions of the mcp SDK
- Source
- MIT licensed, version 1.3.1 on PyPI and GitHub
Safe defaults
Built for something autonomous
A model calling these tools is not reading a warning label first, so the defaults have to do the work.
Four tools return live secrets, because that is what they are for — a connection string without a password is not a connection string. Three return proxy passwords; get_api_access returns a service key when it is asked for one explicitly. Every other tool returns balances, endpoints, usage and targeting data only.
get_proxy_credentialsbuild_proxy_connection_stringgenerate_proxy_listget_api_access
Those four carry an instruction in their own descriptions not to repeat the value back unless it was asked for directly — the protocol has no annotation for a sensitive result, so a description is the only channel that reaches the model at all.
It does mean a credential becomes part of the conversation, and of whatever your client logs. That is worth deciding about deliberately rather than discovering.
What bounds it
- Masking
- One switch, and the credential tools mask or refuse rather than return half a secret
- Spending
- The one tool that charges the balance is not registered unless the server opts in
- Bulk limits
- 50 entries per call, and a larger request is refused rather than quietly clamped
- Errors
- An errored result with a readable reason, never a bare transport failure
Pricing
What it costs
The server costs nothing — it is MIT licensed and installs from PyPI. What runs through it bills exactly as it would from the dashboard or a direct API call: same rates, same balance, no separate plan and no surcharge for arriving over MCP.
| Product | What spends it | Rate |
|---|---|---|
| Scraper API | Scraping, crawling, schemas and schedules | from $0.13/1K results |
| Residential proxies | The default | from $0.49/GB |
| Datacenter proxies | Where speed wins | from $0.30/GB |
| Mobile proxies | Carrier addresses | from $2.20/GB |
Reading credentials, usage or targeting options is free: those calls go to the Public API and spend nothing. Every scraping response also carries what it used and what is left, so the model can see the cost of what it just did. Full plans and volume tiers are on pricing, and every proxy product has a free trial.
Sourcing
Where the IPs come from
No competitor makes this claim on an MCP page, and unsupervised collection is exactly where it matters.
Every residential and mobile IP in the Evomi network comes from someone who opted in through an app that says so, and who is paid for the bandwidth. Their privacy runs the other way too: no customer can see a node’s browsing or device data.
That does not change what the tools return. It changes what you are agreeing to when your agent sends a thousand requests you did not individually approve.
How every IP is sourcedThe network underneath
- Consent
- Volunteer nodes only, opted in and paid for their bandwidth
- Oversight
- Member of the Ethical Web Data Collection Initiative
- Operation
- Swiss-operated by TeraShift GmbH, ISO/IEC 27001 certified
- Limits
- The Acceptable Use Policy bars illegal and email-related use
FAQs
MCP server questions, answered
What is an MCP server?
A server that exposes tools an AI model can call. The Model Context Protocol is an open standard for that connection: the client — Claude, Cursor, your editor — speaks it, the server offers a list of tools with typed arguments, and the model picks which to call and reads the result. Evomi’s server offers tools covering the Scraper API and proxy account management, so a model can collect data and manage the connection it collects over.
Is an “MCP proxy” the same thing as a proxy MCP server?
No, and the two get confused constantly. An MCP proxy — mcp-remote, mcp-proxy, an MCP gateway — is a protocol shim that bridges a client speaking one transport to a server speaking another. It moves protocol traffic. Evomi’s MCP server is a tool provider that happens to sell network access: it moves your scraping traffic through residential, datacenter or mobile IPs. If you were looking for a transport shim, you want the former.
What do I need to install?
The evomi-mcp package from PyPI, on Python 3.10 or newer, and an MCP client that can launch a local process. Nothing else: the command speaks MCP over stdio when it is started with no arguments, which is how a client runs it. The source is MIT licensed and on GitHub if you would rather read it first.
Do I need a paid plan?
You need an Evomi account. Every proxy product has a free trial, and the proxy and account tools — credentials, usage, targeting catalogues, balances — spend nothing at all, because they go to the Public API. Scraping consumes Scraper API credits at the same rate a direct API call would.
Which clients work?
Any client that can start a local MCP server over stdio, which covers Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed, Cline and anything written against the MCP SDKs. A client that only accepts a remote server URL cannot start a local process, so it cannot reach this one.
Can an agent spend money without asking?
Scraping consumes credits, so yes — the same way it would if you ran the API yourself. Two things bound it. get_api_access, get_proxy_usage and get_account_info let you ask what has been spent at any point, and every scraping response reports its own cost inline. And the one tool that charges the account balance directly, order_browser_profile, is not registered at all unless the server is started with EVOMI_ENABLE_SPENDING=1, so a model that has not been given it cannot see that it exists.
Does it return my proxy password to the model?
Four tools can: get_proxy_credentials, build_proxy_connection_string, generate_proxy_list, and get_api_access when the key is asked for explicitly. That is what they are for — a connection string without a password is not a connection string. It does mean the value becomes part of the conversation and of whatever your client logs, which is worth knowing before you point an agent at it. Setting EVOMI_HIDE_PROXY_PASSWORDS=1 masks or refuses all four, and points the model at the tools that return the gateway, ports and targeting values with no credential in them.
What is the difference between this and the Scraper API?
None, underneath. The MCP server is a way for a model to call the Scraper API and the Public API. If you are writing code, call those APIs directly — they are documented, they have clients in Python, JavaScript, Go and Rust, and they express things MCP does not, like bulk batches. If a model is deciding what to collect, MCP is the better surface, because it can discover the tools and read the errors.