Skip to main content
Glama
fusionproxy-mcp

fusionproxy-mcp

Official
README.md
<p align="center">
  <a href="https://fusionproxy.net/?utm_source=github&utm_medium=referral&utm_campaign=fusionproxy-mcp">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/FusionProxies/.github/main/assets/logo-on-dark.png">
      <img src="https://raw.githubusercontent.com/FusionProxies/.github/main/assets/logo-on-light.png" alt="Fusion Proxy" height="52">
    </picture>
  </a>
</p>

# Fusion Proxy MCP server: web access for AI agents through residential proxies

An [MCP](https://modelcontextprotocol.io) server that lets Claude, Cursor, VS Code Copilot and any other MCP client fetch web pages **through residential IPs in the country you choose**. Useful when an agent gets blocked, rate-limited, or needs to see a page the way a visitor from another country sees it.

## Tools

| Tool | What it does |
|---|---|
| `fetch_page(url, country?, session?, output?, max_chars?)` | Downloads a public page through a residential IP and returns it as Markdown (default), plain text or HTML |
| `check_exit_ip(country?, session?)` | Shows the IP, city, country and network that websites see |

- `country`: two-letter code (`us`, `de`, `jp`, ...). Leave it out for any country.
- `session`: any name. Calls with the same name keep the same IP for 10 minutes, so an agent can browse several pages of one site as one visitor.

Example conversation:

> **You:** What does the pricing page of example.com show to visitors from Japan?
>
> *The agent calls `fetch_page(url="https://example.com/pricing", country="jp")` and reads the Markdown.*

What the calls return (IP addresses and networks are placeholders; yours will differ):

```
check_exit_ip {'country': 'jp'}                  -> IP 198.51.100.7, Tokyo, Tokyo, JP (AS64500 Example ISP)
check_exit_ip {'country': 'us', 'session': 'a'}  -> IP 203.0.113.42, Austin, Texas, US (AS64501 Example Broadband)
check_exit_ip {'country': 'us', 'session': 'a'}  -> IP 203.0.113.42, Austin, Texas, US (AS64501 Example Broadband)
fetch_page(https://quotes.toscrape.com/, country=gb) -> Status: 200 ... # [Quotes to Scrape](/) ...
```

The same `session` gives the same IP; a new session or no session gives a new one.

## Setup

You need Fusion Proxy credentials (username and password from the [dashboard](https://dashboard.fusionproxy.net/?utm_source=github&utm_medium=referral&utm_campaign=fusionproxy-mcp); there is a [free trial](https://fusionproxy.net/free-trial?utm_source=github&utm_medium=referral&utm_campaign=fusionproxy-mcp)) and [uv](https://docs.astral.sh/uv/) (or pip).

### Claude Code

```bash
claude mcp add fusionproxy -e FUSION_USER=your_username -e FUSION_PASS=your_password \
  -- uvx --from git+https://github.com/FusionProxies/fusionproxy-mcp fusionproxy-mcp
```

### Claude Desktop

`claude_desktop_config.json` (Settings, Developer, Edit Config):

```json
{
  "mcpServers": {
    "fusionproxy": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/FusionProxies/fusionproxy-mcp", "fusionproxy-mcp"],
      "env": { "FUSION_USER": "your_username", "FUSION_PASS": "your_password" }
    }
  }
}
```

### Cursor

`~/.cursor/mcp.json`: the same `mcpServers` block as for Claude Desktop.

### VS Code

`.vscode/mcp.json`:

```json
{
  "servers": {
    "fusionproxy": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/FusionProxies/fusionproxy-mcp", "fusionproxy-mcp"],
      "env": { "FUSION_USER": "your_username", "FUSION_PASS": "your_password" }
    }
  }
}
```

### Without uv

```bash
pip install git+https://github.com/FusionProxies/fusionproxy-mcp
fusionproxy-mcp   # speaks MCP over stdio; point your client's "command" at it
```

## Settings

| Variable | Required | Meaning |
|---|---|---|
| `FUSION_USER` | yes | Proxy username (main user or a sub-user) |
| `FUSION_PASS` | yes | Proxy password |
| `FUSION_COUNTRY` | no | Default country when a call does not pass one |
| `FUSION_GATEWAY` | no | Gateway `host:port`, default `resi.fusionproxy.net:12286` |

Traffic through the server counts against your residential plan like any other request. A typical HTML page is 50 KB to 2 MB.

## How it works

Each call opens a connection to the Fusion Proxy gateway with the options in the username (`-country-jp`, `-sessid-...-sessTime-600s`), downloads the page with a normal browser User-Agent, follows redirects and converts HTML to Markdown with `html2text`. If a residential connection drops, the call retries once on a new connection. Only public `http` and `https` URLs are accepted: `localhost`, `.local` names and private, loopback or reserved IP addresses are refused.

The server does not run JavaScript. For pages that render in the browser, see [playwright-proxy](https://github.com/FusionProxies/playwright-proxy).

Works with the MCP Python SDK 1.x and 2.x.

## Development

```bash
pip install -e ".[test]"
pytest            # no network and no credentials needed
```

Changes are listed in [CHANGELOG.md](CHANGELOG.md).

## Use responsibly

Fetch public pages only, respect the sites' terms and `robots.txt`, and keep the request rate reasonable.

## Related

- [fusionproxy](https://github.com/FusionProxies/fusionproxy): code examples in 8 languages
- [python-web-scraping](https://github.com/FusionProxies/python-web-scraping): a requests + BeautifulSoup scraper
- [Residential proxies](https://fusionproxy.net/proxies/residential?utm_source=github&utm_medium=referral&utm_campaign=fusionproxy-mcp) from $2.95/GB

## License

MIT, see [LICENSE](LICENSE).

TDQS

A3.8/5.0

Scored across 2 tools

Disambiguation5/5

fetch_page retrieves page content while check_exit_ip is a pure diagnostic that reports the exit IP/geo; their purposes are unmistakably distinct despite sharing the optional country/session parameters. An agent would never confuse the two.

Naming Consistency5/5

Both tools follow the same snake_case verb_noun convention (fetch_page, check_exit_ip), with verbs that accurately describe the action. No mixing of styles or vague names.

Tool Count3/5

Two tools is on the thin side; fetch plus a single diagnostic leaves little room for related operations. The scope is coherent, but the surface is closer to a minimal wrapper than a well-rounded toolset.

Completeness4/5

The core operation (proxied page fetch) and the key verification step (exit IP check) are both present, covering the main workflow. Minor gaps exist: no non-GET requests, no session management (list/clear/expire), and the sticky-IP duration is fixed.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues