About RoamProxy
RoamProxy is an MCP server for AI agents that fetches web pages and provides proxy details through RoamProxy IPs. Requests can target a country, state, or city and use residential, datacenter, or mobile proxies.
Key features
- 01Fetch URLs through geographically selected proxies
- 02Generate rotating or sticky proxy URLs
- 03Inspect proxy exit IP and location
- 04View account balance, prices, and usage
Use cases
- 01Check localized product pages and prices
- 02Compare search results across countries
- 03Create a geo-targeted proxy for Playwright
- 04Review proxy account usage and balance
MCP support
The MCP server exposes tools for fetching URLs, generating proxies, checking exit IPs, and viewing account details. MCP clients configure it with a RoamProxy API token.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y roamproxy-mcpROAM_API_TOKENSecretYour RoamProxy API token (member dashboard > Rotating residential > API)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
4Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | http(s) URL to fetch |
| body | string | No | Request body for POST |
| city | string | No | City name, e.g. 'Los Angeles'. Requires country and state. If the city has no stock the gateway falls back to the state, then the country; check_ip shows where you landed. |
| state | string | No | State/region code, e.g. 'ca', 'ny', 'tx' (US full names like 'California' are also accepted). Requires country. |
| format | enum | No | How to return HTML pages. Default markdown.markdown | text | html |
| method | enum | No | Default GETGET | POST | HEAD |
| country | string | No | ISO 3166-1 alpha-2 country code, e.g. 'us', 'de', 'jp'. Omit for any country. |
| headers | object | No | Extra request headers |
| product | enum | No | Proxy pool. Default residential.residential | datacenter | mobile |
| session | string | No | Sticky session id (letters/digits). Same id = same exit IP for a while. Omit to rotate the IP on every request. |
| max_chars | integer | No | Truncate the body to this many characters. Default 20000. |
Details
From the project READMERoamProxy MCP Server
An MCP server that lets AI agents (Claude, Cursor, VS Code, Windsurf, …) browse the web through RoamProxy residential, datacenter and mobile IPs in 190+ countries.
Ask your agent things like:
- "Open this product page from a US residential IP in Los Angeles and summarise the price."
- "Compare what google.de and google.fr show for 'running shoes'."
- "Give me a sticky UK proxy for Playwright."
- "How much balance is left on my RoamProxy account?"
Tools
| Tool | What it does |
|---|---|
fetch_url | Fetch a URL through a proxy IP in the chosen country / state / city. Returns status + body as markdown, text or HTML. |
get_proxy | Build a ready-to-use http:// or socks5:// proxy URL (plus Playwright config) for any geo, rotating or sticky. |
check_ip | Show the exit IP, city, region and ISP for a geo/session, to verify targeting. |
account_status | Wallet balance, per-GB prices, last 7 days of usage, rented static IPs. |
Geo options on every tool: country (us, de, jp…), state (ca, ny… or full US state names), city (Los Angeles), session (same id = same IP; omit to rotate), product (residential default, datacenter, mobile).
Setup
- Create an account at roamproxy.com and copy your API token from the member dashboard (Rotating residential page, API section).
- Add the server to your client. Requires Node.js 20+.
Claude Code
claude mcp add roamproxy -e ROAM_API_TOKEN=your_token -- npx -y roamproxy-mcp
Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, ~/.cursor/mcp.json, …)
{
"mcpServers": {
"roamproxy": {
"command": "npx",
"args": ["-y", "roamproxy-mcp"],
"env": { "ROAM_API_TOKEN": "your_token" }
}
}
}
VS Code (.vscode/mcp.json)
{
"servers": {
"roamproxy": {
"command": "npx",
"args": ["-y", "roamproxy-mcp"],
"env": { "ROAM_API_TOKEN": "your_token" }
}
}
}
Pricing
Traffic is billed to your RoamProxy wallet exactly as if you used the proxy directly — the MCP server itself is free and open source. Residential $2/GB (down to $1.20/GB with volume top-ups), datacenter $0.80/GB, balance never expires. See pricing.
How it works
fetch_url runs on your machine: the request goes to the RoamProxy gateway (gw.roamproxy.com:41080) and leaves from a residential IP in the location you asked for. Your token only unlocks your own proxy credentials and account info — it cannot top up, buy or change anything.
If a city has no stock the gateway falls back to the state, then the country, instead of failing; check_ip shows where you actually landed.
Development
npm install
npm test # offline unit tests
ROAM_API_TOKEN=... node test/e2e.mjs # live check, uses a little traffic
Related
- proxy-examples — code samples for Python, Node, Go, curl
- roamproxy-python — Python SDK
- proxyprobe — proxy checker CLI
MIT © Goldkeep Digital LLC
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.