roamproxy-mcp

RoamProxy 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