Skip to main content
Glama
@mobileproxy/mcp-server

@mobileproxy/mcp-server

Official
by mobileproxy

@mobileproxy/mcp-server

npm downloads license

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"].

Related MCP server: computer-use-mcp

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

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.

License

MIT

Available Tools

28 tools
add_residential_trafficAdd traffic to a residential proxyA
Destructive
Inspect

Tops up the traffic quota of an existing residential proxy, keeping its geo settings and connection string. Charges the account balance immediately; estimate_only=true returns the amount without charging. The remaining quota is residential_traffic_left_mb in list_proxies.

Inputs: price_id (required), proxy_id (required), num, estimate_only.

attach_proxy_to_adspowerPut a proxy into an AdsPower profileA
DestructiveIdempotent
Inspect

Writes a mobileproxy.space proxy into an AdsPower browser profile through the AdsPower Local API: host, port, login, password and, for mobile proxies, the change-IP link. It REPLACES the profile's current proxy settings, so confirm with the user first. Requires AdsPower running on this computer with its Local API enabled (ADSPOWER_API_KEY must be set if AdsPower security verification is on). profile_id is the AdsPower profile id (user_id). If the profile is open, restart it to apply.

Inputs: proxy_id (required), profile_id (required), protocol.

buy_proxyBuy proxiesA
Destructive
Inspect

Buys one or more mobile, server or backconnect proxies and charges the account balance immediately. With estimate_only=true it returns the total without charging or allocating. country accepts an ISO code or id_country; geoid from get_geo_list pins an exact location. Returns the new proxies with full connection details.

Inputs: period_days (required), type, count, geoid, +5 more.

buy_residentialBuy a residential proxy packageA
Destructive
Inspect

Buys a residential (home ISP) proxy: a traffic bundle rather than a time rental. Charges the account balance immediately; estimate_only=true returns the amount without charging. country is optional: without it the pool is global, and set_residential_geo can change it later for free.

Inputs: price_id (required), num, country, estimate_only.

change_geoChange proxy country / operatorA
Destructive
Inspect

Swaps the underlying modem of a proxy to one in a different country and/or with a different mobile operator, WITHOUT buying a new proxy (the same proxy_id keeps its login/password — only the physical location changes). Pass at least one of: country (ISO code), id_country (numeric), geoid (from get_geo_list — most specific), or operator (name). Use check_after_change=true to have the server verify the new IP is live before returning (adds 1-10s). Subject to a per-proxy cooldown.

Inputs: proxy_id (required), geoid, country, operator, +2 more.

change_proxy_credentialsChange proxy login and passwordA
Destructive
Inspect

Sets a new login and password on one or more proxies, for example after credentials leaked. Without login/password new random ones are generated; the same pair is applied to every proxy in the call. Clients still using the old credentials stop connecting. Returns the new credentials for each proxy.

Inputs: proxy_ids (required), login, password.

diagnose_tcp_fingerprintCheck the TCP fingerprint a site seesA
Read-only
Inspect

Sends a real request through the proxy to fingerprinting endpoints and compares what they observe (TTL, window, MSS, window scale, option order, OS guess) with the applied profile, for example to confirm set_tcp_fingerprint took effect. Slow: up to ~45 seconds. Results are cached for 60 seconds per proxy. One proxy per call, mobile or server only.

Inputs: proxy_id (required).

find_available_geoFind where mobile proxies are availableA
Read-only
Inspect

Answers "where can I get a mobile proxy in <country/city> on , and what does it cost" in one call: locations with free modems, which operators have free modems there, and mobile proxy prices per rental period, replacing a chain of get_geo_list, operator lookups and get_price. city and operator accept Latin or Cyrillic ("Kazan" or "Казань", "megafon" or "Мегафон") and match the start of a word in the location caption / operator name. Captions are mostly English but some come back in Russian; operator names are API ids such as "megafone", "beeline", "tele2", "mts". The returned geoid and operator work as inputs to the purchase and change_geo tools.

Inputs: country (required), city, limit, currency, +2 more.

get_account_historyAccount transaction historyA
Read-only
Inspect

Lists balance operations newest first: top-ups, purchases, renewals and refunds, with the amount, a description that names the proxy (PID) where relevant, and a receipt link when one was issued. Dates are Moscow time. Page with offset.

Inputs: limit, offset.

get_balanceGet account balanceA
Read-only
Inspect

Returns the current account balance in RUB, plus the can_payout amount for accounts with partner status. Purchases and renewals fail with "Insufficient balance" when the balance does not cover them.

Inputs: no named parameters.

get_connection_stringGet ready-to-paste connection stringsA
Read-only
Inspect

Returns a proxy's credentials as ready-to-paste strings: http:// and socks5:// URLs, a host:port:login:password line that most proxy managers and browser-profile tools import, a curl command to test it, and for mobile proxies the change-IP link that such tools accept as a "change IP URL". For residential proxies the strings reflect the current geo settings, which set_residential_geo changes.

Inputs: proxy_id (required).

get_geo_listList available proxy locationsA
Read-only
Inspect

Returns all geo-locations (geoid + human caption + ISO + free-modem count) where proxies are currently available for purchase or migration. Use this to: recommend a location to the user, validate before buy_proxy or change_geo, or filter by country (set country to a 2-letter ISO code). The geoid value is needed for buy_proxy. Cached server-side for 60s and client-side for 5 minutes.

Inputs: country.

get_health_snapshotAccount health checkA
Read-only
Inspect

One-call answer to "is everything OK with my proxies?": balance, proxies expiring soon (flagging whether auto-renewal is on), residential packages running out of traffic, and optionally which dedicated IPs sit on spam blacklists. Returns only what needs attention, ordered critical → warning → info. check_spam=true adds one lookup per mobile/server proxy (up to max_spam_checks), so it is slower.

Inputs: check_spam, max_spam_checks, low_traffic_percent, expiring_within_days.

get_priceGet proxy price quoteB
Read-only
Inspect

Returns mobile proxy prices for a country across all rental periods (1, 3, 7, 14, 30, 60, 90, 180, 365 days). country accepts a 2-letter ISO code (e.g. "RU") or a numeric id_country.

Inputs: country (required), currency.

get_proxy_statusGet current proxy IP & healthA
Read-only
Inspect

Returns the CURRENT external IP of a proxy and optionally checks if that IP is listed in spam/abuse blacklists (Spamhaus, Stop Forum Spam, etc). Use to verify a fresh rotation succeeded, or to decide if you need to rotate again because the IP is dirty. The check_spam=true mode is slower (~3s extra) but is the only way to assess IP quality. For residential proxies the check does not go through the sticky session and returns a different pool IP each time, so it says nothing about the IP a sticky session is using.

Inputs: proxy_id (required), check_spam.

get_residential_locationsList residential geo targetsA
Read-only
Inspect

Lists geo targets available for residential proxies: countries, regions (states), cities or ASNs (carriers). set_residential_geo accepts only the code values returned here; the backend ignores unknown codes and keeps the previous location. Cascade: type="countries" → type="regions" with country → type="cities" with country + region (cities need a region because large countries have thousands). Entries may also carry title_ru, a Russian name, which is absent for small towns.

Inputs: type, region, country.

get_residential_trafficResidential traffic usage by dayA
Read-only
Inspect

Returns daily traffic consumption for a residential proxy. Use it to answer "how much have I used / how long will the bundle last". The REMAINING quota is not here — it comes from list_proxies (residential_traffic_left_mb). Combine both to estimate the burn rate before add_residential_traffic.

Inputs: proxy_id (required), days.

get_tcp_fingerprintShow the TCP fingerprint of proxiesA
Read-only
Inspect

Shows which TCP fingerprint profile each proxy currently imitates (profile_id null = the device's own, unmasked). Mobile and server proxies only; anything else is listed in errors.

Inputs: proxy_ids (required).

list_proxiesList my proxiesA
Read-only
Inspect

Returns all proxies owned by the authenticated user with full connection details (host, port, login, password, geo, operator, expiration), and the proxy_id values other tools take. Supports filtering by type (mobile/server/backconnect/residential) and by country (ISO code or numeric id_country). Backconnect and residential proxies carry no country id, so a country filter excludes them. The server already drops expired proxies, but active_only rechecks client-side as a safety net.

Inputs: type, country, id_country, active_only.

list_residential_plansList residential proxy plansA
Read-only
Inspect

Returns the residential (home ISP) proxy plans with price per GB. Residential is billed by traffic volume (GB bundles) rather than by rental period, so these prices replace get_price for residential. Larger bundles cost less per GB. The price_id identifies a plan for purchase or top-up.

Inputs: no named parameters.

list_tcp_profilesList TCP fingerprint profilesA
Read-only
Inspect

Lists the TCP/IP fingerprint presets a mobile or server proxy can present at the network layer (Android, iPhone, Windows, macOS, Linux…), for making the OS signature of proxied traffic consistent with the client device. set_tcp_fingerprint applies one.

Inputs: category, include_details.

reboot_modemReboot the modem behind a proxyA
Destructive
Inspect

Power-cycles the 4G modem behind a mobile proxy, which clears most hangs where the proxy stops passing traffic and rotate_ip does not help. Active connections drop and the proxy is back in about a minute. Allowed once per 30 minutes per proxy.

Inputs: proxy_id (required).

renew_proxiesRenew proxiesA
Destructive
Inspect

Extends one or more mobile, server or backconnect proxies by a period and charges the account balance immediately, at the rate that applies to each proxy. estimate_only=true returns the total without charging. Auto-renewal settings stay as they are. Residential proxies are extended by traffic instead (add_residential_traffic).

Inputs: proxy_ids (required), period_days (required), estimate_only.

rotate_ipRotate proxy IPA
Destructive
Inspect

Gets a proxy a new exit IP. Mobile proxies (proxy_type=0) reconnect to the carrier and pick up a new cellular IP; residential proxies (proxy_type=3) in sticky mode get a new peer, while in rotating mode the IP already changes on every request. Active connections through the proxy drop. Takes ~3-10 seconds, free of charge, with a short cooldown between rotations. verify=true checks the new IP afterwards (adds ~1-2s).

Inputs: proxy_id (required), verify.

rotate_until_cleanRotate until the IP is cleanA
Destructive
Inspect

Gets a mobile proxy onto an IP that is on no spam/abuse blacklist: rotates, checks the new IP and repeats up to max_attempts, in one call instead of chaining rotate_ip and get_proxy_status. With keep_if_clean=true it checks the current IP first and keeps it when clean. Returns status="cooldown" with wait_seconds when the carrier refuses another rotation yet. Active connections drop on each rotation. Mobile proxies only (proxy_type=0), free of charge.

Inputs: proxy_id (required), max_attempts, keep_if_clean.

set_residential_geoSet residential geo and session modeA
DestructiveIdempotent
Inspect

Reads or changes the geo targeting and session mode of a residential proxy. With only proxy_id it returns the current settings; any other parameter changes them. Free and reversible. Geo codes come from get_residential_locations; the backend ignores unknown codes and keeps the previous location. A change rewrites the provider login, and the response carries the updated http/socks5 connection strings. session_mode="rotating" gives a new IP per request; "sticky" holds one IP for session_time minutes (max 120).

Inputs: proxy_id (required), asn, city, state, +3 more.

set_tcp_fingerprintApply a TCP fingerprint profileA
DestructiveIdempotent
Inspect

Makes mobile or server proxies present a TCP fingerprint profile from list_tcp_profiles, so the network-level OS matches the client device (e.g. a Windows desktop on a Windows profile). profile_id=0 restores the device's own fingerprint. Free and reversible. Delivery to the equipment is queued and takes up to a minute, so diagnose_tcp_fingerprint right after may still show the old values. Residential and backconnect proxies are rejected per proxy in errors.

Inputs: proxy_ids (required), profile_id (required).

update_proxy_settingsUpdate proxy settingsA
DestructiveIdempotent
Inspect

Changes settings on one or more proxies at once: auto-renewal on or off, a comment, and the timer that rotates a mobile proxy's IP automatically every N minutes. Only the settings you pass are changed.

Inputs: proxy_ids (required), comment, auto_renewal, auto_rotate_minutes.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools target a distinct resource+action, and descriptions go out of their way to distinguish near-neighbors (e.g. rotate_ip vs rotate_until_clean, get_geo_list vs find_available_geo, get_price for mobile vs list_residential_plans). A few pairs still overlap conceptually (get_residential_traffic vs list_proxies for traffic, get_tcp_fingerprint vs list_tcp_profiles, get_proxy_status vs rotate_until_clean), but the descriptions resolve them.

    Naming Consistency5/5

    Consistent snake_case verb_noun pattern throughout (get_geo_list, list_proxies, set_tcp_fingerprint, buy_proxy, change_geo, add_residential_traffic). No camelCase or style mixing; the convention is predictable across all 28 tools.

    Tool Count3/5

    28 tools is heavy for the surface, though the domain genuinely spans mobile + residential proxies, TCP fingerprinting, AdsPower integration, and billing. Some granular getters (get_balance, get_account_history, get_price) and convenience wrappers (find_available_geo, rotate_until_clean) could be consolidated, pushing this into the borderline-heavy range.

    Completeness4/5

    Strong lifecycle coverage: purchase, renewal, rotation, geo/credential changes, settings, traffic top-up, and health/billing introspection, plus escape hatches like estimate_only and diagnose_tcp_fingerprint. Minor gaps remain (no cancel/delete/expire-a-proxy operation and no IP whitelist/firewall management), but agents can work around these.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers