Fusion Proxy MCP server
Officialby 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).