MCProxy

An [MCP](https://modelcontextprotocol.io) server that gives AI agents on-demand access to proxies from the world's leading and Russian/CIS proxy providers — through a single, unified interface.

Built with FastMCP 3. When an agent needs a proxy, it calls one MCProxy tool; MCProxy talks to whichever provider you've configured and returns ready-to-use proxy strings.

Why

Every proxy provider has its own API, auth scheme, and quirks. MCProxy normalizes them behind one provider-agnostic tool surface so an agent (or you) can:

• discover which providers are configured and what they support,
• generate or list proxies with geo-targeting and rotation,
• buy and extend proxies where the provider's API allows it,
• check balance / usage and list targetable countries,
• run requests through managed scraping APIs,

…without learning each vendor's API.

How it works

AI agent ──MCP──> MCProxy (FastMCP server)
                      │
                      ├─ unified tools: list_providers, get_proxies,
                      │   generate_proxy_list, buy_proxies, check_balance, …
                      │
                      └─ provider registry ─> per-provider adapters ─HTTP─> vendor APIs

Each provider is a small adapter that maps the vendor's API onto shared models (ProxyEndpoint, BalanceInfo, CountryListResult, …). A registry exposes them, and a handful of generic tools dispatch to the right adapter based on a provider argument. This keeps the tool count low (great for token usage) while supporting many providers.

Supported providers

Implemented adapters

Documented & planned

list_providers also surfaces a catalog of major providers with public APIs whose adapters are planned: Bright Data, Oxylabs, Decodo (Smartproxy), SOAX, NetNut, Infatica, Proxy-Cheap, Zyte, Nimble, Rayobyte (global) and Mobile Proxy Space, iProxy.online, ProxyMarket, Froxy (RU/CIS). See docs/PROVIDERS.md for the full landscape, API notes and sources.

Install

Requires Python 3.12+. uv recommended.

git clone https://github.com/evgenygurin/mcproxy.git
cd mcproxy
uv venv --python 3.12
uv pip install -e .            # add ".[dev]" for tests/linting

Configure

Credentials are read from environment variables (or a local .env). Configure only the providers you use. Copy .env.example and fill in your keys:

cp .env.example .env
# e.g.
WEBSHARE_API_KEY=...
IPROYAL_API_TOKEN=...
PROXY6_API_KEY=...

list_providers shows which providers are configured and the exact env var names each one needs.

Run

# stdio (default — for Claude Desktop, Cursor, etc.)
uv run mcproxy
# or
uv run fastmcp run server.py:mcp

# HTTP transport
MCPROXY_TRANSPORT=http MCPROXY_PORT=8000 uv run mcproxy

Use with an MCP client

{
  "mcpServers": {
    "mcproxy": {
      "command": "uv",
      "args": ["run", "mcproxy"],
      "env": {
        "WEBSHARE_API_KEY": "your-key",
        "PROXY6_API_KEY": "your-key"
      }
    }
  }
}

Tools

Every returned proxy includes a ready-to-use url (e.g. http://user:pass@host:port).

Settings

Global options use the MCPROXY_ prefix:

Development

uv pip install -e ".[dev]"
uv run pytest          # tests (in-memory MCP client + mocked HTTP)
uv run ruff check .    # lint
uv run mypy src        # types

Adding a provider: create src/mcproxy/providers/<name>.py subclassing BaseProvider, override the operations it supports, and register it in src/mcproxy/providers/__init__.py. See webshare.py for a clean reference.

Disclaimer

Use proxies lawfully and in accordance with each provider's terms of service and applicable law. This project is an integration layer; it does not endorse misuse.

License

MIT