# mobileproxy/mcp-server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/mobileproxy/mcp-server  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1768  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-server-145

## Description
MCP server for mobileproxy.space — manage your mobile proxies from Claude, Cursor, Windsurf.

## Tools
Capabilities this server exposes over MCP:

- **list_proxies** — 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.
- **get_proxy_status** — 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.
- **get_balance** — 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.
- **get_account_history** — 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.
- **get_geo_list** — 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.
- **get_price** — 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.
- **rotate_ip** — 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).
- **change_geo** — 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.
- **update_proxy_settings** — 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.
- **change_proxy_credentials** — 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.
- **reboot_modem** — 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.
- **buy_proxy** — 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.
- **renew_proxies** — 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).
- **list_residential_plans** — 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.
- **get_residential_locations** — 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.
- **get_residential_traffic** — 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.
- **set_residential_geo** — 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).
- **buy_residential** — 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.
- **add_residential_traffic** — 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.
- **get_health_snapshot** — 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.
- **find_available_geo** — Answers "where can I get a mobile proxy in <country/city> on <operator>, 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.
- **get_connection_string** — 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.
- **rotate_until_clean** — 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.
- **list_tcp_profiles** — 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.
- **get_tcp_fingerprint** — 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.
- **set_tcp_fingerprint** — 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.
- **diagnose_tcp_fingerprint** — 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.
- **attach_proxy_to_adspower** — 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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

**Requires environment variables:** `MOBILEPROXY_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mobileproxy/mcp-server does

mobileproxy/mcp-server exposes mobileproxy.space account and proxy operations through the Model Context Protocol. It supports mobile, server, backconnect, and residential proxy workflows. Read-only operations can inspect inventory, external IPs, connection strings, balances, transaction history, availability, pricing, TCP profiles, residential traffic, and health conditions.

Write operations can rotate IPs, move proxies between countries or operators, update settings, change credentials, reboot a modem, renew or purchase services, configure TCP fingerprints, and adjust residential targeting. Several operations work in batches, including settings updates for up to 100 proxies, credential changes for up to 50, and TCP fingerprint changes for up to 50.

## How it works

The local package authenticates requests with a mobileproxy.space API key. MCP clients can then call the exposed tools from chat or agent workflows. Read tools only retrieve information. Write tools modify proxies, equipment, or account-related services, and MCP clients may request confirmation before executing them.

Purchases and renewals made by the local build charge the account balance. The hosted endpoint uses quote variants for proxy purchases, renewals, residential purchases, and residential top-ups instead; those return an amount and dashboard link rather than directly charging the balance. The hosted deployment also excludes the local AdsPower bridge.

The TCP fingerprint tools apply or inspect network-level profiles such as Android, iPhone, Windows, macOS, and Linux. Diagnosis can take approximately 45 seconds, and a newly applied profile may take about a minute to reach the equipment. Residential services use traffic bundles rather than rental periods, with separate tools for plans, geo targeting, consumption, and top-ups.

## Setup and configuration

Get an API key from the mobileproxy.space user area before configuring mobileproxy/mcp-server. The npm package can be started with `npx -y @mobileproxy/mcp-server`, and the key is supplied as `MOBILEPROXY_API_KEY`. Docker is also supported with the published image `ghcr.io/mobileproxy/mcp-server` and the same environment variable.

Claude Desktop can use the downloadable `.mcpb` release or a manual MCP configuration. Cursor and Windsurf can use the local stdio configuration shown by the project. Claude Code supports `claude mcp add` with the package and environment variable. A remote deployment is available at `https://mcp.mpsapi.com/mcp`; clients send the API key as a Bearer authorization header. The API key is passed with requests rather than stored as a copy by the server.

## Tools and capabilities

- Inspect proxy health, current IPs, connection strings, balances, history, and account activity.
- List proxies and filter them by type or country.
- Find available modems, locations, operators, prices, and residential targeting options.
- Rotate IPs, rotate until an IP is not on a spam blacklist, change geo, or reboot a modem.
- Configure auto-renewal, comments, rotation timers, credentials, and TCP fingerprints.
- Buy, renew, or top up proxy services, subject to local or hosted purchase behavior.
- Write a proxy and its change-IP link into an AdsPower profile with the local experimental bridge.

## Limitations and notes

The AdsPower attachment tool is experimental, local-build-only functionality, and AdsPower must be running for the documented profile workflow. Modem reboots are limited to once every 30 minutes. Residential geo changes accept values from the residential location list; unknown values are ignored and leave the previous location unchanged. `profile_id=0` restores a native TCP fingerprint. Hosted use does not provide the local AdsPower bridge and does not directly charge purchases, renewals, or top-ups.

_Full upstream README: https://allmcps.com/mcp/mcp-server-145/readme_