mobileproxy.space MCP server

@mobileproxy/mcp-server

Model Context Protocol server for mobileproxy.space — gives Claude Code, Claude Desktop, Cursor, Windsurf and other MCP-compatible agents direct control over your mobile proxies.

Every mobile proxy is a dedicated 4G/LTE modem with a real carrier IP that stays yours for as long as you need, and you rotate it on demand. Typical uses: testing sites and apps the way mobile users in a given country and network see them, checking ads and localized content by geo, price and availability monitoring, and keeping your own traffic private.

Quickstart

Get your API key at mobileproxy.space/user.html?api.

Claude Desktop — one click

Download mobileproxy.mcpb from the latest release, double-click it, paste your API key. Claude Desktop ships its own Node.js, nothing else to install.

Claude Code

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

--scope user stores the key in your user config, not in the project, so it never ends up in git.

Remote server — nothing to install

The hosted endpoint https://mcp.mpsapi.com/mcp runs the same tools, with two differences: it leaves out the local-only AdsPower bridge, and it quotes purchases, renewals and top-ups instead of charging the balance (quote_proxy_purchase, quote_renewal, quote_residential_purchase, quote_residential_topup return the amount and a dashboard link). Install the package locally to buy from the chat.

• claude.ai: Settings → Connectors → Add custom connector → URL https://mcp.mpsapi.com/mcp → paste your API key on the sign-in page.
• 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"}}}}

The server keeps no copy of your key: each request carries it, or an OAuth token that contains it encrypted.

Cursor, Windsurf, Claude Desktop (manual 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) or %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

In an MCP client config use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MOBILEPROXY_API_KEY", "ghcr.io/mobileproxy/mcp-server"].

Быстрый старт по-русски

MCP-сервер даёт Claude, Cursor и другим AI-агентам прямое управление вашими прокси на 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. Попросите агента обычными словами:
   • «Всё ли в порядке с моими прокси?»
   • «Дай строку для импорта прокси 470663 в AdsPower»
   • «Смени IP на прокси 470663, пока не будет чистый»
   • «Где в Казани есть свободные модемы Мегафона и сколько это стоит?»
   • «Пропиши прокси 470663 в профиль AdsPower jc8y5g3» (AdsPower должен быть запущен)
   • «Поставь прокси 470663 TCP-отпечаток Windows 11 и проверь, что видят сайты»
   • «Перенеси прокси 470663 в Турцию»
   • «Сколько стоят 5 прокси в Германии на неделю?»

Покупки агент всегда сначала считает в режиме estimate_only и просит подтверждения — деньги без вашего «да» не списываются.

Available tools

read tools only look things up. write tools change something — a proxy, its settings or the balance — and are annotated as destructive, so MCP clients such as Claude ask before running them. Purchase tools (local build only) also take estimate_only: true for a dry run.

Account and proxies

Tool	Kind	Description
get_health_snapshot	read	What needs attention: expiring proxies (with auto-renewal state), residential packages low on traffic, optionally blacklisted IPs
list_proxies	read	All proxies with connection details; filter by type or country
get_proxy_status	read	Current external IP of a proxy + optional spam-blacklist check
get_connection_string	read	http:// / socks5:// URLs, a host:port:login:password import line, a curl test, and the change-IP link
get_balance	read	Balance in RUB + partner payout amount if any
get_account_history	read	Top-ups, purchases, renewals and refunds with receipt links
update_proxy_settings	write	Auto-renewal, comment and automatic IP-rotation timer for up to 100 proxies at once
change_proxy_credentials	write	New login and password for up to 50 proxies, e.g. after a leak
reboot_modem	write	Power-cycle the modem behind a stuck mobile proxy (once per 30 min)

Mobile, server and backconnect proxies

Tool	Kind	Description
find_available_geo	read	Free modems in a country or city, operators that have them, and prices per period — in one call
get_geo_list	read	All locations (geoid, ISO, free-modem count); filter by country
get_price	read	Prices for every rental period (1/3/7/14/30/60/90/180/365 d) in a country
rotate_ip	write	New exit IP: mobile proxies reconnect to the carrier; sticky residential proxies get a new peer
rotate_until_clean	write	Rotate a mobile proxy until its IP is on no spam blacklist; keep_if_clean keeps a good current IP
change_geo	write	Move a proxy to another country or operator without re-buying
buy_proxy	write	Buy proxies — charges the balance (hosted: quote_proxy_purchase)
renew_proxies	write	Extend up to 100 proxies by a period — charges the balance (hosted: quote_renewal)

TCP fingerprint (mobile and server proxies)

Sets the OS signature a proxy shows at the network level (TTL, window, MSS, TCP option order), so proxied traffic looks like the device it represents — for example a Windows desktop or an iPhone.

Tool	Kind	Description
list_tcp_profiles	read	Presets: Android, iPhone, Windows, macOS, Linux…
get_tcp_fingerprint	read	Which profile each proxy currently presents (null = native)
set_tcp_fingerprint	write	Apply a profile to up to 50 proxies; profile_id=0 restores native. Reaches the equipment within a minute
diagnose_tcp_fingerprint	read	What fingerprinting endpoints observe through the proxy vs. the applied profile (up to ~45 s)

Residential proxies (type 3)

Residential is billed by traffic volume, not by rental period, so it has its own plan, geo and top-up tools.

Tool	Kind	Description
list_residential_plans	read	GB bundles with price per GB
get_residential_locations	read	Countries / regions / cities / ASNs valid for geo targeting
get_residential_traffic	read	Daily consumption and burn rate
set_residential_geo	write	Read or change geo targeting and rotating/sticky mode — free and reversible
buy_residential	write	Buy a traffic bundle — charges the balance (hosted: quote_residential_purchase)
add_residential_traffic	write	Top up a package, keeping its geo and connection string (hosted: quote_residential_topup)

Notes on residential:

• Geo codes come from get_residential_locations. The backend ignores unknown values and leaves the proxy in its previous location.
• Changing geo rewrites the provider login; the response carries the new http/socks5 strings.
• In list_proxies a residential entry has proxy_type: 3, both ports equal (one port serves HTTP and SOCKS5), and a residential_traffic_* quota block.

Local integrations

Tool	Kind	Description
attach_proxy_to_adspower	write	Write a proxy (and the change-IP link) into an AdsPower browser profile — experimental, local build only

attach_proxy_to_adspower talks to the AdsPower Local API on your computer, so AdsPower must be running with its Local API enabled. It is built from AdsPower's API documentation and covered by tests, but not yet verified against a live AdsPower install — please report problems in Issues.

Read tools cache geo and country lookups (5–60 min) to stay within the ~3 requests/sec per-token rate limit.

Configuration

Env var	Default	Purpose
MOBILEPROXY_API_KEY	required	Your API token from /user.html?api
MOBILEPROXY_API_BASE	https://mpsapi.com	API portal, reachable from Russia too; override for dev/staging
MOBILEPROXY_TIMEOUT_MS	30000	HTTP request timeout
MOBILEPROXY_DEBUG	0	Set to 1 for verbose stderr logs
ADSPOWER_API_URL	http://local.adspower.net:50325	AdsPower Local API address, for attach_proxy_to_adspower
ADSPOWER_API_KEY	unset	Only if AdsPower's Local API has security verification on

Running as a remote HTTP server

npx -y @mobileproxy/mcp-server --http (or the Docker image with --http) serves MCP over Streamable HTTP at /mcp. It is stateless and holds no key of its own: clients send their API key as Authorization: Bearer …, and with MOBILEPROXY_OAUTH_SECRET set it also acts as an OAuth 2.1 server for claude.ai connectors. See deploy/README.md for the Docker + nginx setup and every setting.

Client compatibility

Client	Supported	Notes
Claude Desktop	✅	one-click .mcpb, or the JSON block above
Claude Code CLI	✅	claude mcp add ... --scope user; ${env:VAR} also works in .mcp.json
Cursor	✅	hard-code env in config (no substitution)
Windsurf	✅	as Cursor
Cowork / CCD	⚠️	${env:VAR} is not substituted — use user-scope config or a system-wide env var

See docs/INSTALL.md for per-client setup and troubleshooting.

Privacy

This server is a thin client for the mobileproxy.space API; it adds no tracking of its own.

• What it processes: your mobileproxy.space API key and the parameters of each tool call, which it forwards to the mobileproxy.space API (mpsapi.com) to act on your account. It does not read or store your conversations, prompts or files.
• Local install (npm, .mcpb, Docker): everything runs on your computer. The key stays in your MCP client's configuration or your OS keychain.
• Hosted endpoint (mcp.mpsapi.com): no database and no copy of your key. Each request carries the key, or an OAuth access token that contains it encrypted (AES-256-GCM; access tokens expire after 1 hour, refresh tokens after 30 days). The web server keeps standard access logs — time, client IP, request line, status, referrer and user agent; never request bodies or the Authorization header — for troubleshooting and abuse prevention, deleted after 14 days.
• Third parties: none. Requests go only to the mobileproxy.space API; the optional AdsPower bridge talks to AdsPower on your own computer.
• Revoking access: remove the connector in your client, or regenerate the API key at mobileproxy.space/user.html?api, which invalidates every token built on the old key.
• Full policy: the mobileproxy.space Privacy Policy covers account data. Questions: support at mobileproxy.space or GitHub issues.

Links

• Install guide
• Publishing runbook
• MCP Registry entry
• Model Context Protocol

License

MIT