mobileproxy

@mobileproxy/mcp-server

适用于 mobileproxy.space 的 Model Context Protocol 服务，可让 Claude Code、Claude Desktop、Cursor、Windsurf 及其他兼容 MCP 的 Agent 直接控制你的移动代理。

每个移动代理都是一台专用的 4G/LTE 调制解调器，配有真实的运营商 IP，只要你需要就会一直为你保留，并且可以按需轮换。常见用途：测试网站和应用在特定国家和网络中的移动用户视角、按地区检查广告和本地化内容、监控价格和供货情况，以及保护自己的流量隐私。

快速开始

在 mobileproxy.space/user.html?api 获取 API 密钥。

Claude Desktop — 一键安装

从最新版本下载 mobileproxy.mcpb，双击并粘贴 API 密钥。Claude Desktop 自带 Node.js，无需安装其他内容。

Claude Code

claude mcp add mobileproxy --scope user --env MOBILEPROXY_API_KEY=your_api_key -- npx -y @mobileproxy/mcp-server

--scope user 会将密钥存储在你的用户配置中，而不是项目中，因此不会被提交到 git。

远程服务 — 无需安装

托管端点 https://mcp.mpsapi.com/mcp 提供相同的工具，但有两处不同：它不包含仅限本地使用的 AdsPower 桥接功能；购买、续订和充值会生成报价，而不是从余额扣款（quote_proxy_purchase、quote_renewal、quote_residential_purchase、quote_residential_topup 会返回金额和控制面板链接）。如需在聊天中购买，请在本地安装此软件包。

• **claude.ai：**设置 → 连接器 → 添加自定义连接器 → URL https://mcp.mpsapi.com/mcp → 在登录页面粘贴你的 API 密钥。
• Claude Code：

  claude mcp add --transport http mobileproxy https://mcp.mpsapi.com/mcp --header "Authorization: Bearer your_api_key"
  

• Cursor：{"mcpServers": {"mobileproxy": {"url": "https://mcp.mpsapi.com/mcp", "headers": {"Authorization": "Bearer your_api_key"}}}}

服务不会保留你的密钥副本：每个请求都会携带密钥，或携带包含该密钥加密内容的 OAuth 令牌。

Cursor、Windsurf、Claude Desktop（手动配置 JSON）

{
  "mcpServers": {
    "mobileproxy": {
      "command": "npx",
      "args": ["-y", "@mobileproxy/mcp-server"],
      "env": {
        "MOBILEPROXY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。Cursor：~/.cursor/mcp.json。

Docker

docker run -i --rm -e MOBILEPROXY_API_KEY=your_api_key ghcr.io/mobileproxy/mcp-server

在 MCP 客户端配置中使用 "command": "docker"，并设置 "args": ["run", "-i", "--rm", "-e", "MOBILEPROXY_API_KEY", "ghcr.io/mobileproxy/mcp-server"]。

俄语版快速入门

MCP 服务可让 Claude、Cursor 和其他 AI Agent 直接管理您在 mobileproxy.space 的代理：查看代理列表、更换 IP、更换国家和运营商、查询余额、购买代理。

1. 在个人中心获取 API 密钥。
2. 安装：
   • Claude Desktop — 从最新版本下载 mobileproxy.mcpb，双击打开文件并输入密钥。
   • Claude Code — 执行一条命令：

     claude mcp add mobileproxy --scope user --env MOBILEPROXY_API_KEY=ваш_ключ -- npx -y @mobileproxy/mcp-server
     

   • 无需安装 — 远程服务 https://mcp.mpsapi.com/mcp：在 claude.ai 中将其添加为连接器（在登录页面输入密钥）；在 Claude Code 中执行 claude mcp add --transport http mobileproxy https://mcp.mpsapi.com/mcp --header "Authorization: Bearer ваш_ключ"。
3. 用日常语言向 Agent 提出请求：
   • “我的代理都正常吗？”
   • “给我代理 470663 的导入字符串，用于 AdsPower”
   • “更换代理 470663 的 IP，直到找到干净的 IP”
   • “喀山哪里有空闲的 MegaFon 调制解调器？价格是多少？”
   • “将代理 470663 配置到 AdsPower 配置文件 jc8y5g3 中”（AdsPower 必须处于运行状态）
   • “为代理 470663 设置 Windows 11 TCP 指纹，并检查网站能看到什么”
   • “将代理 470663 转移到土耳其”
   • “德国的 5 个代理租用一周要多少钱？”

Agent 始终会先以 estimate_only 模式计算购买费用并请求确认 — 未经您同意，系统不会扣款。

可用工具

读取工具只查询信息。写入工具会更改内容 — 代理、代理设置或余额 — 并标注为破坏性操作，因此 Claude 等 MCP 客户端会在执行前询问。购买工具（仅限本地构建）也支持 estimate_only: true 进行试运行。

账户和代理

工具	类型	描述
get_health_snapshot	读取	查看需要关注的事项：即将到期的代理（包括自动续费状态）、流量不足的住宅套餐，以及可选的被列入黑名单的 IP
list_proxies	读取	查看所有代理及其连接详情；可按类型或国家筛选
get_proxy_status	读取	查看代理当前的外部 IP + 可选的垃圾邮件黑名单检查
get_connection_string	读取	提供 http:// / socks5:// URL、host:port:login:password 导入行、curl 测试和更换 IP 的链接
get_balance	读取	查看 RUB 余额 + 合作伙伴可提现金额（如有）
get_account_history	读取	查看充值、购买、续费和退款记录及收据链接
update_proxy_settings	写入	一次为最多 100 个代理设置自动续费、备注和自动 IP 轮换计时器
change_proxy_credentials	写入	为最多 50 个代理设置新的登录名和密码，例如在凭据泄露后
reboot_modem	写入	为卡住的移动代理重启调制解调器（每 30 分钟一次）

移动、服务器和反向连接代理

工具	类型	描述
find_available_geo	读取	一次调用即可查询某个国家或城市的空闲调制解调器、提供这些调制解调器的运营商，以及各时段的价格
get_geo_list	读取	所有位置（geoid、ISO、空闲调制解调器数量）；可按国家筛选
get_price	读取	某个国家所有租用时段（1/3/7/14/30/60/90/180/365 d）的价格
rotate_ip	写入	获取新的出口 IP：移动代理会重新连接运营商，粘性住宅代理则会更换对等端
rotate_until_clean	写入	轮换移动代理，直到其 IP 未被任何垃圾邮件黑名单收录；keep_if_clean 会保留当前的良好 IP
change_geo	写入	将代理切换到另一个国家或运营商，无需重新购买
buy_proxy	写入	购买代理——会扣除余额（托管模式：quote_proxy_purchase）
renew_proxies	写入	将最多 100 个代理续期一段时间——会扣除余额（托管模式：quote_renewal）

TCP 指纹（移动和服务器代理）

设置代理在网络层呈现的操作系统签名（TTL、窗口、MSS、TCP 选项顺序），使经代理转发的流量看起来像来自其所代表的设备——例如 Windows 桌面电脑或 iPhone。

工具	类型	描述
list_tcp_profiles	读取	预设：Android、iPhone、Windows、macOS、Linux……
get_tcp_fingerprint	读取	查看每个代理当前呈现的配置文件（null = 原生）
set_tcp_fingerprint	写入	为最多 50 个代理应用配置文件；profile_id=0 可恢复为原生配置。设置会在一分钟内应用到设备
diagnose_tcp_fingerprint	读取	查看指纹检测端点通过代理观察到的指纹与已应用配置文件之间的差异（最长约 45 秒）

住宅代理（类型 3）

住宅代理按流量用量计费，而非按租用时段计费，因此有专门的套餐、地理位置和流量充值工具。

工具	类型	描述
list_residential_plans	读取	流量套餐及每 GB 价格
get_residential_locations	读取	可用于地理定位的国家／地区／城市／ASN
get_residential_traffic	读取	每日用量和消耗速率
set_residential_geo	写入	读取或更改地理定位及轮换／粘性模式——免费且可撤销
buy_residential	写入	购买流量套餐——会扣除余额（托管模式：quote_residential_purchase）
add_residential_traffic	写入	为套餐充值，同时保留其地理位置和连接字符串（托管模式：quote_residential_topup）

住宅代理说明：

• 地理位置代码来自 get_residential_locations。后端会忽略未知值，并保留代理的原有位置。
• 更改地理位置会重写提供商登录信息；响应中会包含新的 http/socks5 字符串。
• 在 list_proxies 中，住宅代理条目的 proxy_type: 3，两个端口相同（一个端口同时提供 HTTP 和 SOCKS5 服务），并包含 residential_traffic_* 配额块。

本地集成

工具	类型	描述
attach_proxy_to_adspower	写入	将代理（及更换 IP 的链接）写入 AdsPower 浏览器配置文件——仅限实验性本地构建

attach_proxy_to_adspower 会调用你电脑上的 AdsPower Local API，因此 AdsPower 必须正在运行并启用其 Local API。此功能根据 AdsPower 的 API 文档构建，并已通过测试，但尚未在实际运行的 AdsPower 安装环境中验证——如有问题，请在 Issues 中反馈。

读取工具会缓存地理位置和国家查询结果（5–60 分钟），以符合每个令牌约 3 次请求／秒的速率限制。

配置

环境变量	默认值	用途
MOBILEPROXY_API_KEY	必填	你从 /user.html?api 获取的 API 令牌
MOBILEPROXY_API_BASE	https://mpsapi.com	API 门户，在俄罗斯也可访问；开发/预发布环境可覆盖此值
MOBILEPROXY_TIMEOUT_MS	30000	HTTP 请求超时时间
MOBILEPROXY_DEBUG	0	设为 1 可在 stderr 中输出详细日志
ADSPOWER_API_URL	http://local.adspower.net:50325	AdsPower Local API 地址，供 attach_proxy_to_adspower 使用
ADSPOWER_API_KEY	未设置	仅在 AdsPower 的 Local API 启用了安全验证时需要

作为远程 HTTP 服务运行

npx -y @mobileproxy/mcp-server --http（或使用带有 --http 的 Docker 镜像）会在 /mcp 提供基于 Streamable HTTP 的 MCP 服务。该服务是无状态的，不持有自己的密钥：客户端通过 Authorization: Bearer … 发送 自己的 API 密钥；设置 MOBILEPROXY_OAUTH_SECRET 后，它还会作为 OAuth 2.1 服务，为 claude.ai 连接器提供支持。有关 Docker + nginx 配置及所有设置，请参阅 deploy/README.md。

客户端兼容性

客户端	支持	备注
Claude Desktop	✅	一键安装 .mcpb，或使用上面的 JSON 配置块
Claude Code CLI	✅	claude mcp add ... --scope user；${env:VAR} 在 .mcp.json 中也可用
Cursor	✅	在配置中硬编码环境变量（不支持替换）
Windsurf	✅	与 Cursor 相同
Cowork / CCD	⚠️	不会替换 ${env:VAR} — 请使用用户范围配置或系统级环境变量

有关各客户端的设置和故障排除，请参阅 docs/INSTALL.md。

隐私

此服务是 mobileproxy.space API 的轻量客户端；它不会自行添加任何跟踪功能。

• 处理的内容： 你的 mobileproxy.space API 密钥和每次工具调用的参数。服务会将这些内容转发到 mobileproxy.space API（mpsapi.com），以便在你的账户上执行操作。它不会读取或存储你的对话、提示词或文件。
• 本地安装（npm、.mcpb、Docker）： 所有内容都在你的计算机上运行。密钥保存在 MCP 客户端配置中或你的操作系统密钥链中。
• 托管端点（mcp.mpsapi.com）： 不使用数据库，也不保存你的密钥。每个请求都会携带密钥，或携带包含该密钥的加密 OAuth 访问令牌（AES-256-GCM；访问令牌 1 小时后过期，刷新令牌 30 天后过期）。Web 服务器会保留标准访问日志 — 时间、客户端 IP、请求行、状态码、引荐来源和用户代理；绝不记录请求正文或 Authorization 标头 — 用于故障排除和防止滥用，并在 14 天后删除。
• 第三方： 无。请求只会发送到 mobileproxy.space API；可选的 AdsPower 桥接会与本机计算机上的 AdsPower 通信。
• 撤销访问权限： 在客户端中移除连接器，或前往 mobileproxy.space/user.html?api 重新生成 API 密钥；此操作会使基于旧密钥生成的所有令牌失效。
• 完整政策： mobileproxy.space 隐私政策涵盖账户数据。如有疑问，请通过 mobileproxy.space 联系支持团队，或前往 GitHub issues。

链接

• 安装指南
• 发布操作手册
• MCP Registry 条目
• Model Context Protocol

许可证

MIT