Allows AI agents to browse the web using residential, datacenter, and mobile proxy IPs across 190+ countries.
Also known as roamproxy/roamproxy-mcp, roamproxy-mcp
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Oct 10, 2026
- License
- MIT
What is RoamProxy MCP?
RoamProxy allows AI agents to browse the web using residential, datacenter, and mobile proxy IPs across 190+ countries. It exposes 4 tools, such as fetch_url, get_proxy, check_ip.
Summary generated from the project's README
About RoamProxy MCP server
RoamProxy provides AI agents with the ability to browse the internet using residential, datacenter, and mobile IP addresses across more than 190 countries. This MCP server connects clients like Claude, Cursor, Windsurf, and VS Code to the RoamProxy gateway, allowing models to access web content from specific geographic locations. Users must provide a RoamProxy API token via environment variables to authenticate their account and access proxy services.
The server includes specific tools for web interaction and account management. The fetch_url tool retrieves website content as markdown, text, or HTML through a selected country, state, or city. The get_proxy tool generates ready-to-use HTTP or SOCKS5 URLs, including Playwright configurations. Users can also utilize check_ip to verify their exit location and ISP, or account_status to monitor wallet balances and usage statistics. Traffic costs are billed directly to the user's RoamProxy wallet based on data consumption.
What you can do with it
- 1Localized Web ScrapingRequest an agent to visit a specific product page using a residential IP from a particular city to check pricing.
- 2Cross-Border Search ComparisonAsk an AI to compare search engine results between different countries to see regional variations.
- 3Automated Browser ConfigurationGenerate a specific proxy URL and configuration for use with Playwright testing tools.
- 4Account and Usage MonitoringCheck the remaining balance in your proxy account to manage data spending.
Written from the project's README. Every use case is checked against a quote from it.
How to install RoamProxy MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall RoamProxy MCP in Claude Code
$ claude mcp add --env 'ROAM_API_TOKEN=<YOUR_ROAM_API_TOKEN>' roamproxy-mcp -- npx -y roamproxy-mcpInstall RoamProxy MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"roamproxy-mcp": {
"command": "npx",
"args": [
"-y",
"roamproxy-mcp"
],
"env": {
"ROAM_API_TOKEN": "<YOUR_ROAM_API_TOKEN>"
}
}
}
}Install RoamProxy MCP in VS Code
.vscode/mcp.json
{
"servers": {
"roamproxy-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"roamproxy-mcp"
],
"env": {
"ROAM_API_TOKEN": "<YOUR_ROAM_API_TOKEN>"
}
}
}
}Install RoamProxy MCP in VS Code CLI
$ code --add-mcp '{"name":"roamproxy-mcp","type":"stdio","command":"npx","args":["-y","roamproxy-mcp"],"env":{"ROAM_API_TOKEN":"<YOUR_ROAM_API_TOKEN>"}}'Install RoamProxy MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"roamproxy-mcp": {
"command": "npx",
"args": [
"-y",
"roamproxy-mcp"
],
"env": {
"ROAM_API_TOKEN": "<YOUR_ROAM_API_TOKEN>"
}
}
}
}Install RoamProxy MCP in Codex
$ codex mcp add roamproxy-mcp --env 'ROAM_API_TOKEN=<YOUR_ROAM_API_TOKEN>' -- npx -y roamproxy-mcpInstall RoamProxy MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.roamproxy-mcp] command = "npx" args = ["-y", "roamproxy-mcp"] [mcp_servers.roamproxy-mcp.env] ROAM_API_TOKEN = "<YOUR_ROAM_API_TOKEN>"
Install RoamProxy MCP in Gemini CLI
$ gemini mcp add -s user -e 'ROAM_API_TOKEN=<YOUR_ROAM_API_TOKEN>' roamproxy-mcp npx -- -y roamproxy-mcpInstall RoamProxy MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"roamproxy-mcp": {
"command": "npx",
"args": [
"-y",
"roamproxy-mcp"
],
"env": {
"ROAM_API_TOKEN": "<YOUR_ROAM_API_TOKEN>"
}
}
}
}RoamProxy MCP tools 4
Detected from the READMEfetch_urlget_proxycheck_ipaccount_status
| fetch_url | — | |
| get_proxy | — | |
| check_ip | — | |
| account_status | — |
Configuration
ROAM_API_TOKENRequiredSecretYour RoamProxy API token (member dashboard > Rotating residential > API)
| Name | Description | |
|---|---|---|
| ROAM_API_TOKEN | Your RoamProxy API token (member dashboard > Rotating residential > API) | RequiredSecret |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableroamproxy/roamproxy-mcp is public and reachablegithub.com/roamproxy/roamproxy-mcp ↗Pass
- Package names this repository as its sourceroamproxy-mcp names roamproxy/roamproxy-mcp as sourcenpmjs.com/package/roamproxy-mcp ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for roamproxy-mcpnpmjs.com/package/roamproxy-mcp/v/0.1.1#provenance ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-10github.com/roamproxy/roamproxy-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from roamproxy-mcpPass
- No critical advisory in the package or its dependencies102 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubRoamProxy 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
RoamProxy MCP questions
How do I add RoamProxy MCP to Claude Code?
Run claude mcp add --env 'ROAM_API_TOKEN=<YOUR_ROAM_API_TOKEN>' roamproxy-mcp -- npx -y roamproxy-mcp in your terminal. Add --scope user to make it available in every project.
How do I add RoamProxy MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does RoamProxy MCP provide?
It exposes 4 tools, including fetch_url, get_proxy, check_ip, account_status.
How much does the MCP server cost?
The MCP server is free and open source, but traffic is billed to your RoamProxy wallet at standard rates.
What happens if a specific city is unavailable?
If a city has no stock, the gateway automatically falls back to the state or country level instead of failing.