Proxy302

proxy302-mcp

Official Proxy302 MCP server, built and maintained by the Proxy302 team. For account, billing or connection questions contact Proxy302 support; for bugs in this server, open a GitHub issue.

Give your AI assistant a real residential-proxy toolbox. proxy302-mcp is a Model Context Protocol server for Proxy302: check your traffic and usage, browse countries and plans, get a rotating residential proxy URL for any country, list your proxies and static IPs, and fetch a web page through a proxy, all from Claude Code, Claude Desktop, Cursor or any MCP client.

中文说明

v1 is deliberately read-only and spend-free: it never buys, renews or tops up anything. The one write it can do (creating a dynamic proxy credential) is free, off by default, and only bills traffic when you actually use it.

Hosted server (no install)

Proxy302 also runs this server for you. Create an API key in the Proxy302 console first.

Sign in with OAuth: add https://mcp.proxy302.com/mcp as a custom connector in Claude, ChatGPT or any client that supports MCP sign-in, and paste your API key once in the sign-in window. In Claude Code:

claude mcp add --transport http proxy302 https://mcp.proxy302.com/mcp

Then run /mcp in Claude Code to sign in.

Or send the key as a header: use https://proxy302.com/v1/mcp with Authorization: Bearer <key id>:<secret>.

claude mcp add --transport http proxy302 https://proxy302.com/v1/mcp --header "Authorization: Bearer <key id>:<secret>"

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "proxy302": {
      "url": "https://proxy302.com/v1/mcp",
      "headers": { "Authorization": "Bearer <key id>:<secret>" }
    }
  }
}

The hosted server has the same tools except fetch_url, plus rotate_ip (fresh exit IP for sticky proxies), check_ip_purity (blocklist score of your static IPs, or of the IPs a location would hand out next) and estimate_cost (quote a plan against your wallet). It never spends money either.

Run it locally

1. Create an API key in the Proxy302 console and note its key id and secret.
2. Install:

claude mcp add proxy302 -e PROXY302_API_KEY="<key id>:<secret>" -- npx -y github:proxy302/proxy302-mcp

Requires Node.js 20+.

Bonus: Proxy302 credits 1 PTC to paid accounts the first time a call through proxy302-mcp succeeds (once per account).

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "proxy302": {
      "command": "npx",
      "args": ["-y", "github:proxy302/proxy302-mcp"],
      "env": { "PROXY302_API_KEY": "<key id>:<secret>" }
    }
  }
}

Cursor

~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "proxy302": {
      "command": "npx",
      "args": ["-y", "github:proxy302/proxy302-mcp"],
      "env": { "PROXY302_API_KEY": "<key id>:<secret>" }
    }
  }
}

Tools

Not in v1, on purpose: purchases, renewals, top-ups.

Examples

Ask your assistant:

• "How much proxy traffic do I have left, and what did I use this week?"
• "Which countries can I use? Get me a Germany proxy."
• "Fetch https://example.com/pricing from a US exit and summarise it."
• "List my static IPs that expire in the next 7 days."

Use the proxy in Playwright

get_dynamic_proxy returns host, port, username and password:

import { chromium } from 'playwright';

const browser = await chromium.launch({
  proxy: { server: 'http://HOST:PORT', username: 'USERNAME', password: 'PASSWORD' },
});
const page = await browser.newPage();
await page.goto('https://ipinfo.io/json');
console.log(await page.textContent('body'));

Use the proxy in browser-use

from browser_use import Agent, Browser, BrowserConfig

browser = Browser(config=BrowserConfig(
    proxy={"server": "http://HOST:PORT", "username": "USERNAME", "password": "PASSWORD"},
))
agent = Agent(task="Open ipinfo.io and tell me the country", llm=llm, browser=browser)

fetch_url is a plain HTTP request without JavaScript rendering. For JavaScript-heavy sites, hand the proxy URL to a browser as above.

Configuration

Credentials are read from the environment only. Never commit them. Requests identify themselves with User-Agent: proxy302-mcp/<version> and X-Proxy302-Client.

Development

npm install
npm run build
npm test
PROXY302_API_KEY="<id>:<secret>" npm run smoke   # read-only checks against the live API

License

MIT