RoamProxy

What RoamProxy MCP server does

RoamProxy MCP server gives MCP-compatible agents access to RoamProxy proxy infrastructure. Agents can request a page through a chosen country, state, or city and receive the response as Markdown, plain text, or HTML. The available IP products are residential, datacenter, and mobile, with residential used by default.

The server also creates proxy connection details for external use. A tool response can include an HTTP or SOCKS5 proxy URL and Playwright configuration, allowing an agent or automation script to reuse a selected location. Sessions can be rotating or sticky: omitting a session identifier allows rotation, while reusing the same identifier keeps the session tied to the same IP.

How it works

The server runs as a local Node.js process and sends proxy traffic through the RoamProxy gateway at gw.roamproxy.com:41080. The requested country, state, city, product, and session determine the proxy selection. If the requested city has no available stock, the gateway falls back to the state and then the country instead of returning an immediate failure.

check_ip helps confirm the result of that selection by reporting the exit IP, city, region, and ISP. This is useful when precise geographic targeting matters, especially where availability causes the actual location to differ from the requested city.

Setup and configuration

RoamProxy MCP server requires Node.js 20 or newer and a RoamProxy account. Create an account, copy the API token from the member dashboard’s Rotating residential API section, and expose it as ROAM_API_TOKEN when starting the server.

For a command-line setup, Claude Code can register the server with claude mcp add, passing the token as an environment variable and launching npx -y roamproxy-mcp. Other listed configurations use the same npx -y roamproxy-mcp command with the token in the client’s MCP environment settings. The README provides examples for Claude Desktop, Cursor, Windsurf, and VS Code.

The MCP package itself is free and open source, but proxy traffic is charged to the RoamProxy wallet under the provider’s normal pricing. The server’s token can access proxy credentials and account information; it cannot top up the wallet, purchase products, or modify account settings.

Tools and capabilities

• fetch_url requests a URL through a proxy selected by geography and product, returning a status and body in Markdown, text, or HTML.
• get_proxy builds an HTTP or SOCKS5 proxy URL and a Playwright configuration for rotating or sticky sessions.
• check_ip reports the exit IP and observed location details for a geography or session.
• account_status reports wallet balance, per-gigabyte prices, usage from the last seven days, and rented static IPs.

All tools accept the documented geographic fields: country, state, city, session, and product. Country values can use codes such as us, de, or jp; states can use abbreviations or full US state names; and cities can be supplied by name.

Limitations and notes

RoamProxy MCP server is intended for proxy-backed requests and account inspection, not account management. Its API token does not provide wallet top-ups, purchases, or other account changes. Geographic requests are subject to proxy availability, and a city-level request may resolve to a broader state or country location. Use check_ip when the effective exit location must be verified.

Traffic consumption is billed to the associated RoamProxy wallet. The README lists residential and datacenter pricing and states that unused balance does not expire; current provider pricing should be checked before use. Live end-to-end testing consumes a small amount of traffic, while the project’s unit tests run offline.