Skip to main content
Glama
Fusion Proxy MCP server

Fusion Proxy MCP server

Official
by fusion-proxy
README.md
<p align="center">
  <a href="https://fusionproxy.net/?utm_source=github&utm_medium=fusionproxy-mcp">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fusion-proxy/fusion-proxy/main/assets/logo-on-dark.png">
      <img src="https://raw.githubusercontent.com/fusion-proxy/fusion-proxy/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.*

Tested output from a real session:

```
check_exit_ip {'country': 'jp'}                  -> IP 60.85.55.0, Tokyo, Tokyo, JP (AS17676 SoftBank Corp.)
check_exit_ip {'country': 'us', 'session': 'a'}  -> IP 47.156.138.80, Walnut, California, US (AS5650 Verizon Business)
check_exit_ip {'country': 'us', 'session': 'a'}  -> IP 47.156.138.80, Walnut, California, US (AS5650 Verizon Business)
fetch_page(https://quotes.toscrape.com/, country=gb) -> Status: 200 ... # [Quotes to Scrape](/) ...
```

## Setup

You need Fusion Proxy credentials (username and password from the [dashboard](https://dashboard.fusionproxy.net/?utm_source=github&utm_medium=fusionproxy-mcp); there is a [free trial](https://fusionproxy.net/free-trial?utm_source=github&utm_medium=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/fusion-proxy/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/fusion-proxy/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/fusion-proxy/fusionproxy-mcp", "fusionproxy-mcp"],
      "env": { "FUSION_USER": "your_username", "FUSION_PASS": "your_password" }
    }
  }
}
```

### Without uv

```bash
pip install git+https://github.com/fusion-proxy/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 `http` and `https` URLs are accepted.

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

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

## Use responsibly

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

## Related

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

## License

MIT, see [LICENSE](LICENSE).