MCProxy

An MCP 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

Provider	Region	Types	Operations
Webshare	🌍 US	datacenter, ISP, residential	list, balance, usage, countries
IPRoyal	🌍 LT	residential	generate, balance, usage, countries
ProxyMesh	🌍 US	datacenter, ISP	list, countries, usage
ScraperAPI	🌍 US	scraping API	scrape, usage
ScrapingBee	🌍 FR	scraping API	scrape, usage
Proxy6	🇷🇺 RU	datacenter (IPv4/IPv6)	list, balance, countries, buy, extend
ProxyLine	🇷🇺 RU	datacenter (IPv4/IPv6)	list, balance, countries, buy, extend
Proxy-Store	🇷🇺 RU	datacenter, residential, mobile	list, balance, countries, buy, extend
Proxy-Seller	🇷🇺 RU	IPv4/IPv6/ISP/mobile/residential	list, balance, countries
ASOCKS	🇷🇺 RU/CIS	residential, mobile	balance
FineProxy	🇷🇺 RU	datacenter, ISP, residential	balance

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

Tool	Purpose
list_providers	Discover providers, capabilities and config status. Start here.
get_provider_info	Capabilities for one provider.
get_proxies	List proxies already on your account (fixed-IP providers).
generate_proxy_list	Generate proxy strings with geo + rotation (residential pools).
buy_proxies	Purchase new proxies (spends money; supported providers only).
extend_proxies	Renew existing proxies by ID.
check_balance / get_usage	Monitor spend and traffic.
list_countries	Targetable locations for a provider.
scrape	Fetch a URL through a managed scraping API.
acquire_proxy	"Just give me a proxy" — picks a configured provider automatically.

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

Settings

Global options use the MCPROXY_ prefix:

Variable	Default	Description
MCPROXY_TRANSPORT	stdio	stdio, http, or sse.
MCPROXY_HOST / MCPROXY_PORT	127.0.0.1 / 8000	HTTP bind address.
MCPROXY_REQUEST_TIMEOUT	30	Outbound HTTP timeout (seconds).
MCPROXY_DEFAULT_PROVIDER	–	Preferred provider for acquire_proxy.

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