IpnProxy MCP

Connect IpnProxy to your AI assistant with the MCP server

The IpnProxy MCP server lets AI assistants manage your proxies and browse the web through them. Ask in plain language:

• “How much residential traffic do I have left, and when will it run out at this rate?”
• “Give me 20 sticky US proxies in New York, in user:pass@host:port format.”
• “Rotate the IP on port 11003.”
• “Open this product page through a German residential IP and summarize the price.”

The same key also works with the REST API for your own scripts.

1. Create an API key

1. Open Dashboard → API Keys.
2. Give the key a name (e.g. Claude Desktop) and choose its permissions:

Permission	Allows
Read (always on)	Balance, orders, usage, locations, generating proxy lists, fetching pages through your proxies
Manage	Rotating IPs, rebooting, changing allowed / whitelisted IPs, resetting the residential proxy password
Orders	Buying bandwidth and plans, extending proxies — paid from your balance only and capped by a daily spend limit you set

3. Copy the key. It is shown once; we only store a fingerprint of it.

Treat the key like a password. If it leaks, revoke it in Dashboard → API Keys — it stops working immediately.

2. Connect your AI assistant

The server runs on your computer with Node.js 20.18 or newer.

• Claude Code
• Claude Desktop
• Cursor
• Other clients

claude mcp add ipnproxy --env IPNPROXY_API_KEY=ipn_live_YOUR_KEY -- npx -y @ipnproxy/mcp-server

Open Settings → Developer → Edit Config and add:

{
  "mcpServers": {
    "ipnproxy": {
      "command": "npx",
      "args": ["-y", "@ipnproxy/mcp-server"],
      "env": { "IPNPROXY_API_KEY": "ipn_live_YOUR_KEY" }
    }
  }
}

Restart Claude Desktop.

Add the same block to ~/.cursor/mcp.json (or Settings → MCP → Add new server).

Any MCP client that supports stdio servers works: run npx -y @ipnproxy/mcp-server with the IPNPROXY_API_KEY environment variable.

Tools

The assistant only sees the tools your key is allowed to use.

Account

Tool	What it does
get_account	Balance, key permissions and daily spend limit
list_orders	Orders across all products
list_plans	Plans and prices of a product

Residential

Tool	Permission	What it does
residential_get_plan	Read	Credentials, total / used / remaining GB
residential_get_usage	Read	Traffic and requests per hour or day
residential_list_countries	Read	Available countries
residential_list_targets	Read	States, cities, ZIP codes and ASNs inside a country
residential_generate_proxies	Read	Proxy lines, identical to the dashboard generator
residential_list_allowed_ips	Read	IPs allowed without a password
residential_rotate_ip	Manage	New IP for one sticky port
residential_add_allowed_ip / residential_remove_allowed_ip	Manage	Edit allowed IPs
residential_reset_password	Manage	New proxy password (old proxy lines stop working)
residential_buy_bandwidth	Orders	Buy GB with your balance

Sticky sessions are port based. Each sticky line uses its own port starting at 11000; rotate a session by its port. Rotating proxies get a new IP on every request.

Premium datacenter

Tool	Permission	What it does
datacenter_list_orders	Read	Active orders, threads and expiry
datacenter_list_countries	Read	Available countries
datacenter_generate_proxies	Read	Rotating or sticky proxy lines for an order
datacenter_buy	Orders	Buy a plan with your balance

Mobile

Tool	Permission	What it does
mobile_list_orders	Read	Active orders
mobile_get_proxies	Read	Endpoints of an order
mobile_list_locations / mobile_list_carriers	Read	Available locations and carriers
mobile_update_whitelist_ip	Manage	Change the whitelisted IP (once per 30 minutes)
mobile_buy	Orders	Buy ports with your balance

Premium mobile

Tool	Permission	What it does
premium_mobile_list_orders	Read	Active proxies with credentials and expiry
premium_mobile_rotate_ip	Manage	Change the IP
premium_mobile_reboot	Manage	Reboot the device
premium_mobile_set_rotation_interval	Manage	Automatic IP change every N minutes
premium_mobile_extend	Orders	Extend by one period with your balance

Browsing and testing (run on your computer)

Tool	What it does
fetch_url	Fetches a page through a proxy and returns markdown, text or HTML. Uses a rotating residential proxy in the country you choose, or any proxy line you pass.
check_ip	Shows the public IP a proxy exits from
test_proxy	Success rate, latency and exit IPs of a proxy

fetch_url does not run JavaScript and caps pages at 5 MB. Traffic counts towards your plan.

Safety

• Spending is opt-in. Paid tools exist only for keys with the Orders permission, pay from your balance only, and stop at the key’s daily limit.
• Price confirmation. Every paid tool requires max_price: the assistant has to show you the price first, and the purchase is refused if the real price is higher.
• Untrusted pages. Pages fetched with fetch_url are marked as untrusted content so the assistant does not follow instructions hidden in them.
• Emails. You get an email whenever a new API key is created on your account.

REST API

Base URL: https://api.ipnproxy.com/api/v1 — send the key as Authorization: Bearer ipn_live_YOUR_KEY (or X-API-Key).

curl https://api.ipnproxy.com/api/v1/residential/proxies \
  -H "Authorization: Bearer ipn_live_YOUR_KEY" \
  -G -d type=sticky -d country=us -d quantity=5 -d format=user:pass@host:port

Method	Path	Permission
GET	/account, /orders, /products/{product}/plans	Read
GET	/residential, /residential/usage, /residential/countries, /residential/targets, /residential/proxies, /residential/allowed-ips	Read
POST	/residential/rotate-ip, /residential/allowed-ips, /residential/reset-password · DELETE /residential/allowed-ips	Manage
POST	/residential/buy	Orders
GET	/premium-datacenter/orders, /premium-datacenter/countries, /premium-datacenter/proxies	Read
POST	/premium-datacenter/buy	Orders
GET	/mobile/orders, /mobile/orders/{id}/proxies, /mobile/locations, /mobile/carriers	Read
POST	/mobile/buy	Orders
POST	/mobile/orders/{id}/whitelist-ip	Manage
GET	/premium-mobile/orders	Read
POST	/premium-mobile/orders/{id}/rotate, /reboot, /rotation-time	Manage
POST	/premium-mobile/orders/{id}/extend	Orders

{product} is one of residential, premium-datacenter, mobile, premium-mobile.

Limits: 120 requests per minute per key; 20 per minute for changes and purchases.

Errors are JSON with a message: 401 invalid or revoked key · 403 missing permission or daily spend limit reached · 402 insufficient balance · 409 price above max_price · 422 validation error · 429 too many requests.