proxies-sx-mcp-server

@proxies-sx/mcp-server

适用于 Proxies.sx 的 MCP（Model Context Protocol）服务：住宅和移动代理，面向 AI Agent，按 GB 计费。Claude、Cursor 和任何 MCP 客户端都可以获取轮换或粘性 HTTP/SOCKS5 代理 URL、查看各国家/地区的实时库存、轮换 IP 并自行管理用量，适用于网页抓取、数据收集和浏览器自动化。

主要产品是 Pool Gateway：一个端点 gw.proxies.sx（HTTP 7000、SOCKS5 7001），代理用户名用于指定所需的代理池、国家/地区和会话。使用此服务，Agent 可以读取实时库存、获取凭据、构建代理 URL、监控用量，并在出现问题时创建支持工单。它还可以管理运营商调制解调器上的专用端口、Private Pools 和 Reserved IPs。

每个工具都带有 MCP 注释（readOnlyHint、destructiveHint），因此客户端可以在删除、轮换或取消操作前征求确认。

快速开始

1. 在 client.proxies.sx/account 创建 API 密钥，并在 client.proxies.sx/purchase 添加流量（GB）。
2. 将服务添加到客户端。Claude Code：

claude mcp add proxies-sx -e PROXIES_API_KEY=psx_your_api_key_here -- npx -y @proxies-sx/mcp-server

3. 请求代理：

查看德国的 Pool Gateway 库存，然后给我一个该地区的粘性住宅代理 URL。

Agent 会调用 pool_get_stock、pool_get_my_credentials 和 pool_build_proxy_url，并返回类似 http://psx_abc123-peer-de-iptype-residential-sid-job1-rot-sticky:[email protected]:7000 的 URL。

API 密钥权限范围

客户密钥可以包含：ports:read、ports:write、ports:rotate、billing:read、account:read、account:write、traffic:read、tickets:read、tickets:write。选择全部权限即可使用完整的客户工具集。

• 客户密钥不提供 billing:write。需要此权限的工具（purchase_shared_traffic、create_crypto_payment、cancel_crypto_payment）仅适用于经销商和管理员密钥；客户需在控制面板中购买流量。
• pak_ 密钥工具（pool_mint_key 和其他 pool_*_key 工具）需要经销商账户，其密钥需包含 customers:read 和 customers:write。
• ops_* 工具仅响应具有 ops:* 权限范围的管理员密钥。

Pool Gateway 规则

用户名语法为 psx_<account>-<pool>-<country>[-token-value ...]。pool_build_proxy_url 会为你生成用户名；以下是其背后的规则。

• 两个池。 peer 是主网络：覆盖大多数国家的住宅和移动设备。mbl 是恰好分布在六个国家的运营商调制解调器：US、GB、FR、NL、PL 和 GE。GE 指格鲁吉亚，而非德国，因此 mbl-de 永远不可用：请使用 peer-de。any 和 best 可让网关自行选择。pool_get_stock 显示当前在线资源。
• IP 类型。 -iptype-mobile、-iptype-residential 或 -iptype-isp。ISP（静态）类型是托管在服务器上的 ISP 注册网络地址；只有明确指定时才会提供。
• 轮换。 sticky 和 hard 都会保持使用同一设备。auto5、auto10、auto20 和 auto60 会按相应间隔切换到另一台设备（默认值为 auto10）。ondemand 会在每次新连接时重新选择。
• 会话需要 -sid-。 sticky、hard 和 auto* 只有在用户名包含 -sid-<id>（小写字母、数字和 _）时，才会在不同连接间保持会话。-session- 不是有效令牌：网关会忽略它，且不会报错。
• Sticky 保持的是设备，而非 IP。 移动运营商可能会更改被保持使用的调制解调器的出口 IP。若要 IP 地址保持不变，请使用住宅 peer 或 Reserved IP。
• 每个账户的限制： 500 个并发连接和 250 个会话。
• 价格： 按流量 GB 计费；购买量越大，每 GB 价格越低；时间免费。get_pricing 会读取实时价格表。两个池的价格相同。
• 代理密码。 网关密码是账户的代理密码（pool_get_my_credentials），或 pak_ 密钥，不是账户登录密码。

网关错误

请求失败时，网关会返回 CODE: message (req: id)。pool_explain_error 会将这些错误转换为后续处理建议。

代码	状态	含义
E_AUTH_REQUIRED	407	未发送代理凭据
E_AUTH_INVALID	407	用户名或代理密码遭拒
E_BALANCE_EXHAUSTED	407	凭据正确，但账户没有剩余流量
E_CAP_EXCEEDED	407	pak_ 密钥已达到其 GB 流量上限
E_RATE_LIMITED_AUTH	429	登录失败次数过多
E_RATE_LIMITED_CONN	429	超出连接数限制
E_SESSION_LIMIT	429	超出会话数限制
E_NO_STOCK_COUNTRY	502	该池、国家和筛选条件下没有在线资源
E_STOCK_DEGRADED	502	请求期间设备断开
E_SSRF_BLOCKED	403	目标是私有地址或元数据地址
E_WRONG_PORT	400	将 HTTP 发送到 SOCKS5 端口，或反之
E_INTERNAL	503	意外的网关错误

工具调用失败时会返回 MCP 错误结果（isError: true），其文本末尾会针对常见情况附上 What to do: 行：API 密钥缺失或已撤销、缺少权限范围、触发速率限制或服务器错误。错误文本会遮蔽密钥和密码。

模式与配置

模式	设置项	工具
API 密钥（标准）	PROXIES_API_KEY	以下所有工具，x402 钱包组除外
x402 钱包（可选）	AGENT_WALLET_KEY	x402 钱包组，以及标记为“也列于钱包模式”的工具
两者	两个变量	全部工具

变量	描述
PROXIES_API_KEY	来自 client.proxies.sx/account 的 psx_ API 密钥
PROXIES_EMAIL、PROXIES_PASSWORD	API 密钥的替代方式：使用账户凭据登录
AGENT_WALLET_KEY	Base 网络上 USDC 钱包的私钥（0x...），用于无需账户的 x402 付款
BASE_RPC_URL	自定义 Base RPC 端点，用于 x402（默认值为 https://mainnet.base.org）
PROXIES_API_URL	API 基础 URL。默认值为 https://api.proxies.sx；末尾的 /v1 会被接受并忽略。除非你运行私有 API，否则请留空。

与 MCP 客户端搭配使用

每个客户端都运行相同的命令 npx -y @proxies-sx/mcp-server，并在环境中设置 PROXIES_API_KEY。

Claude Code

claude mcp add proxies-sx -e PROXIES_API_KEY=psx_your_api_key_here -- npx -y @proxies-sx/mcp-server

添加 -s user，即可在每个项目中使用。也可以在项目根目录中放置一个 .mcp.json，并使用以下 JSON。

Claude Desktop

将内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows），然后重启 Claude Desktop：

{
  "mcpServers": {
    "proxies-sx": {
      "command": "npx",
      "args": ["-y", "@proxies-sx/mcp-server"],
      "env": {
        "PROXIES_API_KEY": "psx_your_api_key_here"
      }
    }
  }
}

Cursor

在 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）中使用相同的 JSON。

Windsurf

在 ~/.codeium/windsurf/mcp_config.json 中使用相同的 JSON。

Docker

docker build -t proxies-sx-mcp https://github.com/bolivian-peru/proxies-sx-mcp-server.git
docker run -i --rm -e PROXIES_API_KEY=psx_your_api_key_here proxies-sx-mcp

容器通过标准输入/输出使用 MCP 通信（必须使用 -i）。

更多配置示例

recipes/ 中提供了适用于 LangChain、CrewAI 和原始 MCP 客户端的可运行示例。

工具

由版本 3.0.1 的代码通过 npm run build:manifest 生成。请勿手动编辑。

Pool Gateway

工具	功能
pool_get_stock	获取 Pool Gateway 的实时库存，无需账户。钱包模式下也会列出。
pool_get_facets	列出一个国家中有库存的城市、州、运营商（含 ASN 和类别）及 IP 类别，并显示数量，无需账户。钱包模式下也会列出。
pool_build_proxy_url	构建可直接使用的 Pool Gateway 代理 URL（gw.proxies.sx，HTTP 7000 或 SOCKS5 7001）。钱包模式下也会列出。
pool_explain_error	解释 Pool Gateway 错误并说明如何处理。钱包模式下也会列出。
pool_get_my_credentials	获取你的 Pool Gateway 代理用户名和代理密码，以及可直接使用的 HTTP 和 SOCKS5 URL。
pool_set_proxy_password	设置新的代理密码（至少 6 个字符）。
pool_get_my_stats	获取你自己的 Pool Gateway 流量和开放连接数，以及代理池的健康评分和连接到该代理池的设备数量。
pool_list_sessions	列出你保存的 Pool Gateway 会话：代理池、国家、运营商、轮换模式、字节数和最近活动时间。
pool_close_session	根据 pool_list_sessions 返回的 sessionKey 关闭一个 Pool Gateway 会话。
pool_close_all_sessions	关闭账户保存的所有 Pool Gateway 会话。

Private Pool 和 Reserved IPs

工具	功能
private_pool_list	列出你的 Private Pool，包括国家、状态、网关用户名、密码已屏蔽的连接字符串（private_pool_reveal 可显示密钥）以及剩余 GB。
private_pool_build	使用账户现有的 GB 余额创建 Private Pool：无需购买，流量从同一余额中计量。
private_pool_reveal	显示 Private Pool 的网关密码（pak_ 密钥）。
private_pool_usage	获取 Private Pool 每天的流量，单位为 MB。
reserved_ip_list	列出 Private Pool 持有的 Reserved IP：国家、类别、运营商、城市、轮换模式、设备是否在线、最近检测到的出口 IP，以及密码已屏蔽的连接字符串。
reserved_ip_reserve	为 Private Pool 保留一个设备，使其他客户无法通过该设备路由流量，并获取密码已屏蔽的连接字符串。
reserved_ip_rotate	立即将 Reserved IP 切换到同一国家/地区的另一台设备。
reserved_ip_extend	更改 Reserved IP 在无流量时的保留时长。
reserved_ip_set_rotation	设置 Reserved IP 是否按计划切换到另一台设备：关闭（固定使用该设备，默认设置），或每隔 5、10、20 或 60 分钟轮换。
reserved_ip_release	将 Reserved IP 归还共享代理池。

账户

工具	功能
get_account_summary	获取账户余额、空闲端口槽位、已购买和剩余流量，以及任何账户提醒。
get_account_usage	获取已购买、已使用和剩余流量，并分别显示 Pool Gateway 流量和专用端口流量。

账单

工具	功能说明
get_pricing	获取实时的每 GB 价格、批量折扣、免费端口槽位档位以及你当前所在的档位。
calculate_price	计算指定 GB 数量在应用批量折扣后的价格。
purchase_shared_traffic	使用账户余额购买 GB 流量。
coupon_validate	检查优惠码是否适用于某笔订单，但不使用该优惠码。
coupon_redeem	兑换独立优惠码，为账户增加免费 GB 流量或端口槽位。
get_payment_history	列出账户过去的付款记录和加密货币充值订单。

加密货币付款

工具	功能说明
create_crypto_payment	创建加密货币订单，为账户余额充值，并返回托管付款链接。
check_crypto_payment_status	检查加密货币订单是否仍处于未付款、确认中、已付款、已过期或已取消状态，以及余额是否已入账。
get_pending_crypto_payments	列出账户尚未完成的加密货币订单及其付款链接。
cancel_crypto_payment	取消尚未付款的加密货币订单。
get_crypto_payment_info	检查当前是否可以使用加密货币充值，以及付款页面接受哪些币种。

专用端口

工具	功能说明
list_available_countries	列出当前可创建专用端口的国家，以及 create_port 所需的 countryId。
list_ports	列出你的专用端口，以及其状态、国家、运营商、到期时间和端口 ID。
get_port	获取一个专用端口的信息，包括其位置以及可直接使用的 HTTP 和 SOCKS5 连接字符串（包含端口密码）。
create_port	在运营商调制解调器上创建专用端口，并返回其连接字符串。
delete_port	删除专用端口并释放其槽位。
update_port_credentials	更改专用端口的登录名和/或密码。
update_os_fingerprint	设置专用端口呈现的操作系统指纹（TCP/IP 特征）。
reconfigure_port	将专用端口迁移到其他国家、运营商或城市。
extend_port	延长专用端口的到期时间。

端口状态

工具	功能说明
get_port_status	检查专用端口是否在线、离线或已过期。
get_port_ip	获取专用端口监听的服务器地址。
ping_port	测试专用端口是否有响应并测量其延迟。
speed_test_port	通过专用端口运行速度测试（下载、上传、ping）。

端口轮换

工具	功能说明
rotate_port	将专用端口迁移到同一位置的另一台调制解调器。
check_rotation_availability	检查专用端口当前是否可以轮换、冷却时间还剩多久，以及有多少台其他调制解调器空闲。
configure_auto_rotation	开启或关闭专用端口的自动轮换，并设置轮换间隔。
get_rotation_history	获取专用端口过去的轮换记录：轮换时间、触发方式、迁移到的位置以及是否成功。
get_rotation_token_url	获取专用端口的公开轮换链接。

实用工具

工具	功能说明
get_proxy_connection_string	生成专用端口的 HTTP 或 SOCKS5 连接字符串（包含端口密码）。
get_all_proxy_formats	以各种常见格式获取专用端口信息：URL、host:port、环境变量、curl、Python 和 Node.js 代码片段，以及其公开轮换链接。
get_service_status	检查 Proxies.sx 当前是否运行正常：Pool Gateway 中未解决的事件、API、网关和中继的状态，以及近期运行时间。钱包模式下也会列出此工具。
get_os_fingerprint_options	列出 create_port 和 update_os_fingerprint 接受的操作系统指纹值。

支持

工具	功能
create_support_ticket	创建支持工单，由 Proxies.sx 的工作人员阅读并回复。
list_my_tickets	列出你的支持工单及其状态和 ID。
get_ticket	获取一张支持工单，包括原始消息和所有回复。
reply_to_ticket	回复你的一张支持工单。
close_ticket	问题解决后，关闭你的一张支持工单。

池访问密钥（经销商账户）

工具	功能
pool_mint_key	为一位客户创建池访问密钥（pak_）；该密钥用作代理密码。
pool_list_keys	列出你的池访问密钥及其用量、流量上限和到期时间；密钥值会被隐藏。
pool_topup_key	一次性增加池访问密钥的流量上限（GB），和／或延长其到期时间。
pool_update_key	更改池访问密钥的标签、启用状态、流量上限、到期时间或质量等级。
pool_regenerate_key	替换池访问密钥的 pak_ 密钥值。
pool_reveal_key	显示池访问密钥的完整 pak_ 密钥值。
pool_delete_key	删除池访问密钥。
pool_key_usage	获取一个池访问密钥每天的流量，单位为 MB。
pool_key_audit	获取一个池访问密钥的审计日志，按时间从新到旧排列：创建、更改、充值、重新生成、显示、删除，以及成功或失败的网关登录记录。

x402 会话管理

工具	功能
get_x402_session	获取你的 x402 会话详情，包括所有端口。
list_x402_ports	列出你的 x402 会话中的所有端口，包括连接字符串和到期时间
get_x402_port_status	获取指定端口的详细状态，包括流量用量和连接信息
get_sessions_by_wallet	列出与你的钱包地址关联的所有 x402 会话。
get_session_status	快速查看会话状态，包括流量用量和到期时间
replace_x402_port	将 x402 会话中的离线端口替换为另一台设备上的新端口，无需付费。
calculate_x402_topup	计算为 x402 会话增加流量和／或时长的费用。
topup_x402_session	为 x402 会话增加流量和／或时长。

运维（仅限管理员密钥）

工具	功能
ops_get_user	客户 360 度视图：余额、池网关用量、端口，以及（若为农场主）其 AI 备注。
ops_get_user_audit	最近对该用户执行的运维 Agent 操作。
ops_reconcile_payments	只读的 Stripe 与数据库付款对照视图，显示用户的已确认总额和待处理金额。
ops_list_tickets	列出支持工单（管理员视图）。
ops_reply_ticket	回复工单，可选择是否通过电子邮件通知客户。
ops_set_slots	设置用户的端口槽位上限（有上限）。
ops_credit_balance	为用户余额充值美元（管理员充值）。
ops_email_user	向一位用户发送个性化电子邮件（受每小时发送速率限制）。
ops_list_farmers	列出农场主的 AI 备注（共享运营记忆）。
ops_get_farmer	农场主设备群漏斗（总数／在线／已验证／已上架／可路由）+ AI 备注。
ops_write_farmer_note	撰写或追加农场主 AI 备注（情况、下一步操作、自由备注）——与未来的 AI 会话共享。

x402 钱包（可选，无需账户）

工具	功能说明
x402_get_proxy	通过从 Agent 钱包支付 USDC，在一台运营商调制解调器上购买专用移动代理；无需账户。
x402_get_pricing	获取实时 x402 每 GB 价格、最低购买量、允许的时长和支付网络，并比较购买费用与钱包余额。
x402_list_sessions	列出此钱包通过本机购买的活跃 x402 代理会话，并显示位置、到期时间和代理主机。
x402_check_session	获取 x402 代理会话的状态、剩余时间、已用流量和连接字符串。
x402_wallet_balance	获取 Agent 钱包地址，以及其在 Base 网络上的 USDC 和 ETH（Gas）余额。
x402_rotate_ip	将 x402 代理切换到另一台调制解调器，以获取不同的出口 IP。
x402_list_countries	列出当前可通过 x402_get_proxy 创建代理的国家，以及空闲调制解调器的数量。
x402_extend_session	为 x402 代理会话增加时长。
x402_service_status	检查 x402 支付服务是否正常运行，并显示钱包余额以及活跃或即将到期的会话数量。
x402_get_pool_access	通过从 Agent 钱包支付 USDC，购买 Pool Gateway 流量；无需账户。
x402_pool_credit	获取 x402 池会话已购买、已使用和剩余的 GB 数。
x402_pool_topup	为 x402 池会话增加 GB 和／或时长。
x402_pool_regenerate	更换 x402 池凭据的密码，例如在密码泄露后更换。
x402_pool_connection	再次显示 x402 池会话的网关主机、端口、用户名和密码。
x402_pool_usage	获取 x402 池会话每天的流量，单位为 MB。
x402_pool_pricing	获取可通过 x402 购买的 Pool Gateway 套餐，以及实时每 GB 价格和最低购买量。

tools.json 以机器可读格式包含相同的列表（名称、类别、标题、描述的首句、只读和破坏性标记、模式、参数）。

专用端口

专用端口将一个端口绑定到一台运营商调制解调器。调制解调器仅位于 US、GB、FR、NL、PL 和 GE（Georgia）；list_available_countries 会显示当前有空闲调制解调器的地点。其他国家／地区请使用 Pool Gateway。

• rotate_port 会将端口切换到另一台调制解调器。登录名和密码保持不变，端口号会改变，每 5 分钟允许轮换一次。
• reconfigure_port 会在另一个地点创建新端口并移除旧端口：端口 ID 会改变。
• API 不会返回端口的出口 IP。请通过代理发送请求以查看该 IP。

私有池和保留 IP

私有池是独立的网关凭据，仅限你选择的国家／地区，并从账户的 GB 余额中扣款（private_pool_build）。保留 IP 会为该池独占一台设备（reserved_ip_reserve），直到你释放该设备或空闲时段结束。服务器会保留每个国家／地区的部分库存，不供预留，并限制对等设备可被占用的时长；拒绝预留时，服务器会说明原因。ISP（静态）类别无法预留。

池或保留 IP 的连接字符串会以 pak_******** 作为密码返回：请将其替换为 private_pool_reveal 返回的密钥。

reserved_ip_list 会显示在保留设备上最近一次看到的出口 IP。该信息仅对所有者显示：请勿公开。

x402：无需账户即可付费（可选）

在 Base 网络上持有已充值 USDC 钱包的 Agent，无需 Proxies.sx 账户即可通过 x402 协议购买流量：API 会返回包含价格的 402 Payment Required，服务会在链上付款，并使用交易哈希重试。设置 AGENT_WALLET_KEY 即可启用钱包工具。

• x402_get_pool_access 可购买 Pool Gateway 流量：为该层级（peer 或 mbl）的每个国家提供一个凭证。x402_pool_pricing 可读取实时层级和价格。
• x402_get_proxy 可购买运营商调制解调器上的一个专用端口。x402_list_countries 显示哪些国家有空闲端口，x402_get_pricing 显示实时价格。
• 钱包需要有 USDC 用于购买，并在 Base 上持有少量 ETH 用于支付 Gas。x402_wallet_balance 可显示两者。（API 也接受由客户端自行付款的 Solana USDC；此服务的钱包则在 Base 上付款。）

账户方式（API 密钥和已充值的 GB）是标准方式；对于无法持有账户的 Agent，x402 是一种替代方案。

分享带宽赚取收益

通过 peer SDK 分享连接的设备会按提供的流量 GB 数获得报酬。条款和设置说明：agents.proxies.sx/peer/skill.md。

Registry

Registry	条目
Official MCP Registry	io.github.bolivian-peru/proxies-sx-mcp-server（参见 server.json）
npm	@proxies-sx/mcp-server
Glama	glama.ai/mcp/servers/bolivian-peru/proxies-sx-mcp-server
Claude Desktop 扩展（MCPB）	manifest.json，由 npm run build:manifest 生成

故障排除

• 启动时显示“Authentication required”。 客户端启动服务时所处的环境中，既未设置 PROXIES_API_KEY，也未设置 AGENT_WALLET_KEY。
• 每个工具都返回 401。 密钥错误、已过期或已撤销。请前往 client.proxies.sx/account 创建新密钥。
• 工具返回 403“missing required scope”。 请创建包含所需权限范围的密钥。客户密钥不能授予 billing:write 和 customers:*（参见上文）。
• 代理返回 407。 查看错误代码：E_AUTH_INVALID 表示代理密码错误（使用 pool_get_my_credentials）；E_BALANCE_EXHAUSTED 表示余额不足（使用 get_account_usage）。
• 代理返回 502 E_NO_STOCK_COUNTRY。 该池、国家和筛选条件下没有设备在线：请检查 pool_get_stock 和 pool_get_facets，并注意 mbl 仅在六个国家提供。
• Claude Desktop 未显示此服务。 检查配置文件的 JSON 语法，确认已安装 Node.js 18 或更高版本，然后彻底重启应用。

开发

npm install
npm run build            # compile to dist/
npm test                 # unit tests: registry, routes, username grammar, error mapping
npm run lint
npm run build:manifest   # regenerate manifest.json, tools.json and the tool lists in the docs

# Read-only check of every tool against production (needs a real key, changes nothing):
PROXIES_API_KEY=psx_... node tests/live-smoke.mjs

链接

• 网站：proxies.sx
• 客户控制台：client.proxies.sx
• Agent 文档：agents.proxies.sx，Pool Gateway 指南：agents.proxies.sx/pool/skill.md
• 支持：create_support_ticket 工具、client.proxies.sx/tickets 或 [email protected]
• x402 规范：x402.org

许可证

MIT License，详见 LICENSE。