Roam Proxy MCP server

Name: Roam Proxy MCP server (roamproxy-mcp)
Author: Roam

Published: 9 October 2026 · Version 0.1.0 · MIT licence

In short: roamproxy-mcp is a free, open-source Model Context Protocol server. Add it to Claude, Cursor, VS Code or any MCP client and your agent can open web pages from a residential IP in a chosen country, state or city, hand out proxy URLs for Playwright or curl, and check your balance. Traffic is billed to your Roam wallet exactly as if you used the proxy yourself.

GitHub npm Claude Desktop (.mcpb) Smithery

What you can ask the agent

"Open this product page from a US residential IP in Los Angeles and tell me the price."
"Compare what google.de and google.fr show for running shoes."
"Give me a sticky UK proxy for Playwright and write the launch code."
"Check which IP and ISP a Japanese session exits from."
"How much balance is left on my Roam account?"

Tools

Tool	What it does
`fetch_url`	Fetches a URL through a proxy IP in the chosen location. Returns HTTP status and the body as markdown, text or HTML.
`get_proxy`	Builds a ready-to-use `http://` or `socks5://` proxy URL, plus a Playwright config, rotating or sticky.
`check_ip`	Shows the exit IP, city, region and ISP for a location or session.
`account_status`	Wallet balance, per-GB prices, the last 7 days of usage and your rented static IPs.

Every tool takes the same location options: country (us, de, jp…), state (ca, ny… or a full US state name), city, session (same id keeps the same IP; leave it out to rotate) and product (residential, datacenter or mobile).

Set up in two minutes

1. Get your API token

Log in to the member dashboard (or create an account).
Open Residential (rotating) in the left menu.
Switch to the API / code tab and copy the token at the top.

2. Add the server to your client

Requires Node.js 20 or newer. Replace your_token with the token from step 1.

Claude Code

claude mcp add roamproxy -e ROAM_API_TOKEN=your_token -- npx -y roamproxy-mcp

Claude Desktop: download roamproxy-mcp.mcpb, double-click it, and paste your token when asked. Or add the JSON below to claude_desktop_config.json.

Cursor, Windsurf, Claude Desktop (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" }
    }
  }
}

How it works

The server runs on your machine. When the agent calls fetch_url, the request goes from your machine to the Roam gateway (gw.roamproxy.com:41080), which forwards it out of an IP in the location you asked for. It is the same gateway and the same per-GB billing as a manual proxy setup. The MCP server only saves the agent from building usernames by hand.

The API token unlocks your own proxy credentials and account summary, nothing more. It cannot top up, buy static IPs or change settings.

No account yet? Register and verify your email to get 50MB of trial traffic, plus 250MB more on your first top-up. That is enough to connect the server and watch the agent fetch a few pages from another country.

FAQ

Does the MCP server cost anything?

The server is free and open source (MIT). Traffic it sends is billed to your Roam wallet at the normal rate: $2/GB rotating residential (down to $1.20/GB with volume top-ups), $0.8/GB rotating datacenter. No subscription, no minimum, and the balance does not expire.

What can the agent do with my API token?

Use your proxies and read your balance, usage and static IP list. The token cannot top up, buy static IPs, change settings or touch other accounts. You can reset it any time from the member dashboard, which invalidates the old one.

Where does fetch_url run?

On your own machine. The server sends the request to the Roam gateway, which forwards it out of an IP in the location you asked for. Roam does not run a hosted browser or store page contents.

I asked for a city but landed somewhere else.

If a city has no available IP at that moment, the gateway falls back to the same state, then the same country, instead of failing. Use check_ip to see where a session actually landed. For US states you can pass either the code (ca) or the full name (California).

Other ways to connect

Not using an AI agent? The same proxies work everywhere: browser extension for Firefox and Edge, code samples for Python, Node, Go and curl, and the Python SDK.

Roam is the exit-IP layer behind the server: rotating residential at $2/GB, rotating datacenter at $0.8/GB, static residential at $4/IP/month, no monthly minimum. Create an account and your agent can be online through a new country in a couple of minutes.