Proxy302

proxy302-mcp

Proxy302 官方 MCP 服务，由 Proxy302 团队构建并维护。有关账户、账单或连接的问题，请联系 Proxy302 支持；有关此服务的错误，请提交 GitHub issue。

为你的 AI 助手配备真正的住宅代理工具箱。proxy302-mcp 是面向 Proxy302 的模型上下文协议服务：查看流量和用量、浏览国家和套餐、获取任意国家的轮换住宅代理 URL、列出你的代理和静态 IP，并通过代理抓取网页，所有操作都可以在 Claude Code、Claude Desktop、Cursor 或任何 MCP 客户端中完成。

中文说明

v1 特意设计为只读且不产生费用：它不会购买、续订或充值任何内容。它唯一可以执行的写入操作（创建动态代理凭据）是免费的，默认关闭，并且只有在你实际使用时才会产生流量费用。

托管服务（无需安装）

Proxy302 也会为你运行此服务。请先在 Proxy302 控制台中创建 API 密钥。

点击一次即可添加 https://mcp.proxy302.com/mcp；随后应用会打开 Proxy302 登录窗口，你只需粘贴一次 API 密钥（key id:secret）。在控制台中删除密钥即可断开连接。

• Claude（claude.ai、Claude Desktop）：Settings → Connectors → Add custom connector，URL 为 https://mcp.proxy302.com/mcp。
• ChatGPT（开发者模式）：使用相同的 URL 和 OAuth 创建连接器。
• **Cursor、VS Code、Windsurf 及其他 MCP 客户端：**使用相同的 URL，无需请求头。

**使用 OAuth 登录：**在 Claude、ChatGPT 或任何支持 MCP 登录的客户端中，将 https://mcp.proxy302.com/mcp 添加为自定义连接器，然后在登录窗口中粘贴一次 API 密钥。在 Claude Code 中：

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

然后在 Claude Code 中运行 /mcp 以登录。

**或者通过请求头发送密钥：**使用 https://proxy302.com/v1/mcp，并设置 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>" }
    }
  }
}

托管服务包含相同的工具，但不包括 fetch_url，此外还提供 rotate_ip（为粘性代理更换出口 IP）、check_ip_purity（检查静态 IP 的黑名单评分，或查看某个位置接下来会分配的 IP 的评分）和 estimate_cost（根据你的钱包余额估算套餐费用）。它同样不会花费任何资金。

本地运行

1. 在 Proxy302 控制台中创建 API 密钥，并记下密钥 ID 和密钥。
2. 安装：

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

需要 Node.js 20+。

额外福利：付费账户首次成功通过 proxy302-mcp 发起调用时，Proxy302 会赠送 1 PTC（每个账户限一次）。

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（或项目中的 .cursor/mcp.json）：

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

工具

工具	功能
get_account_usage	账户、钱包（PTC）余额、剩余预付流量、各流量池余额，以及最近 N 天的每日用量
list_countries	可定位的国家/地区，包含 ID 和 ISO 代码（可按名称筛选）
list_regions	某个国家/地区的州，或某个州的城市
list_products	产品线和静态 IP 套餐（数据中心和住宅）
get_dynamic_proxy	获取一个可直接使用的 http://user:pass@host:port 住宅轮换代理 URL，支持指定国家/地区（以及支持时指定州/城市）。复用现有代理；create_if_missing=true 时创建一个代理
list_my_proxies	列出你的动态代理和静态 IP；除非请求，否则密码会被遮盖
fetch_url	通过代理请求 URL（可选择指定国家/地区），并返回 Markdown、文本或原始内容

v1 中有意不包含：购买、续订、充值。

示例

向助手提问：

• “我还剩多少代理流量？这周用了多少？”
• “我可以使用哪些国家/地区？给我一个德国代理。”
• “通过美国出口节点抓取 https://example.com/pricing 并总结内容。”
• “列出我将在未来 7 天内到期的静态 IP。”

在 Playwright 中使用代理

get_dynamic_proxy 会返回主机、端口、用户名和密码：

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'));

在 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 是不进行 JavaScript 渲染的普通 HTTP 请求。对于依赖大量 JavaScript 的网站，请像上面那样将代理 URL 交给浏览器使用。

配置

变量	含义
PROXY302_API_KEY	必填。<key id>:<secret>，或 Basic ... 令牌
PROXY302_API_SECRET	可选；当 PROXY302_API_KEY 仅包含 key id 时使用
PROXY302_BASE_URL	可选；默认值为 https://proxy302.com

凭据仅从环境变量中读取。切勿提交凭据。请求会使用 User-Agent: proxy302-mcp/<version> 和 X-Proxy302-Client 标识自身。

开发

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

许可证

MIT