# IPRoyal MCP MCP

> IPRoyal Proxy Services manages your entire global proxy infrastructure right from your AI agent. You monitor traffic usage, rotate credentials instantly, and manage whitelists without touching a dashboard. Use this MCP to get precise bandwidth statistics for residential or datacenter proxies and generate dynamic connection strings based on country or sticky sessions.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** proxy-management, web-scraping, traffic-monitoring, credential-rotation, geo-targeting

## Description

Running web scraping operations means managing complex proxy networks constantly. Instead of jumping between dashboards just to check funds or update credentials, you talk to your agent. It handles the whole process: checking if you have enough budget using `get_profile`, verifying IP availability across dozens of countries, and generating a perfectly formatted connection string for any target region. You also maintain security by instantly rotating usernames and passwords when needed. Because it’s available on Vinkius, you can connect this proxy intelligence to your existing AI client—whether that’s Claude or Cursor—and keep all your data collection steps in one conversation flow.

## Tools

### add_whitelist_ip
Authorizes a specific IP address for proxy access without requiring a user/pass in the connection string.

### get_availability
Checks if specific proxy IPs are available in target regions before starting a crawl.

### list_countries
Retrieves country codes and region identifiers needed to build accurate geo-targeted connection strings.

### change_credentials
Updates the username and password for an existing proxy order to fix suspected leaks or change keys.

### list_whitelisted_ips
Shows which IP addresses are currently authorized to connect without credentials.

### list_orders
Lists all current proxy orders, providing necessary IDs for traffic lookup or credential changes.

### get_profile
Retrieves your overall account balance and profile details to check funding levels.

### generate_proxy_string
Creates a formatted connection string that supports geographic targeting or sticky IP sessions.

### remove_whitelist_ip
Revokes a specific IP address's access from the proxy endpoint for security purposes.

### get_traffic
Provides precise statistics on the bandwidth consumed by a proxy order.

## Prompt Examples

**Prompt:** 
```
Check my IPRoyal account balance
```

**Response:** 
```
I've retrieved your profile details. Your current account balance is $45.20 USD. Your account status is 'Active' and your email is alex@example.com. Would you like to see your active proxy orders?
```

**Prompt:** 
```
How much traffic have I used for order ID '123456'?
```

**Response:** 
```
For order 123456 (Residential Proxies), you have consumed 12.45 GB of traffic. You have 37.55 GB remaining in your current allocation. Would you like to rotate the credentials for this order?
```

**Prompt:** 
```
Generate a proxy connection string for Germany with sticky session
```

**Response:** 
```
Generating proxy string… For Germany (DE) with a sticky session, your connection string is: `geo.iproyal.com:10000:username_country-de_session-abc123:password`. You can use this directly in your scraping script.
```

## Capabilities

### Track Usage and Funds
Get real-time bandwidth consumption statistics for your proxy orders, preventing unexpected depletion of funds.

### Secure Access Control
Authorize or revoke specific client IP addresses to secure scrapers without needing proxy credentials.

### Credential Lifecycle Management
Instantly update usernames and passwords for your proxy orders to maintain security hygiene and prevent leaks.

### Geo-Targeted Connection Building
Generate complex connection strings that include country codes or guarantee a sticky IP session.

### Infrastructure Auditing
List all active proxy orders and check account details to plan large scraping runs.

## Use Cases

### Large Scale Geo-Targeted Crawl
A data scientist needs to scrape competitor pricing only in Germany. They ask the agent to check availability first using `get_availability`, then request a proxy string for Germany, and finally run the job while monitoring traffic via `get_traffic`.

### Security Audit & Cleanup
An ops engineer decommissioned an old server. They tell their agent to run `remove_whitelist_ip` using the former server's IP, ensuring that access is immediately cut off and preventing unauthorized use.

### Credential Rotation After Breach
A developer suspects a credential leak for an important proxy order. They ask the agent to execute `change_credentials` right away, updating both the username and password without needing to restart their scripts.

### Building a Robust Proxy Pipeline
An automation developer is building a new multi-country scraper. They first run `list_countries` to get all necessary region codes, then use these codes with `generate_proxy_string` to build the connection logic.

## Benefits

- Avoid manual checks. Instead of logging into a separate dashboard to check funds, just ask your agent for `get_profile` details. You know if you have enough budget before starting any big job.
- Maintain security easily. If credentials are leaked, running `change_credentials` updates the username and password immediately. It's faster than changing them manually across all scripts.
- Target specific regions reliably. Use `list_countries` to get the necessary country codes (like 'us' or 'de') then let your agent use `generate_proxy_string` to build a perfect connection string for that region.
- Secure headless scrapers by whitelisting IPs. Rather than baking credentials into source code, you can authorize an IP using `add_whitelist_ip`, which keeps things cleaner and safer.
- Monitor bandwidth usage in real-time. With residential proxies billed by traffic, running `get_traffic` prevents unexpected billing spikes when a crawl hits its limits.

## How It Works

The bottom line is you talk to your agent about proxies; it uses this MCP to execute the commands.

1. Subscribe to this MCP on Vinkius.
2. Provide your IPRoyal API Access Token in the configuration.
3. Directly ask your AI client for an action, like 'What's my current traffic usage?' or 'Generate a proxy string for France.'

## Frequently Asked Questions

**How do I check my current budget using get_profile?**
You ask your agent to get your profile details. It returns your overall account balance and status, letting you know if you can afford a large scraping run.

**What is the difference between list_orders and list_whitelisted_ips?**
`list_orders` shows all purchased proxy batches (Residential, Datacenter), while `list_whitelisted_ips` only lists IPs authorized for direct connection without credentials.

**How do I create a string for multiple countries using generate_proxy_string?**
You specify the list of target countries and whether you need sticky sessions. The agent combines all that information into one usable, dynamic proxy connection string.

**Can I revoke an IP address with remove_whitelist_ip?**
Yes, running `remove_whitelist_ip` immediately revokes a specific IP's access to the proxy endpoints. This is how you secure it if the machine changes or gets decommissioned.

**How do I use `add_whitelist_ip` to secure my scrapers?**
You authorize a new IP address by running `add_whitelist_ip`. This is key for security, letting your headless scrapers connect without needing the username and password in the source code.

**What information does `list_countries` provide before I build a proxy string?**
`list_countries` gives you the necessary country codes and region identifiers (like 'us' or 'de'). You need this specific list to format complex, accurate geo-targeted connection strings.

**I think my credentials leaked; how should I use `change_credentials`?**
Run `change_credentials` immediately. This updates the username and password for a given proxy order, which is critical for stopping unauthorized access right away.

**Should I check IP availability using `get_availability` before running a crawl?**
Yes, call `get_availability`. It checks if IPs are actually available in your target region (by default residential) before you generate the proxy string and waste time.

**Can I check how much bandwidth I've consumed for a specific proxy order?**
Yes. Use the `get_traffic` tool with your Order ID. Your agent will return the exact amount of data used in GB/MB, helping you avoid unexpected depletion of funds for residential proxies.

**How do I whitelist my server's IP address through my agent?**
The `add_whitelist_ip` tool allows your agent to authorize a specific IPv4 address for a proxy order. This enables user/pass-free authentication, which is more secure for headless scrapers and backend servers.

**Can I check if residential proxies are available in a specific country?**
Absolutely. Use the `get_availability` tool and specify the product (e.g. 'residential'). Your agent will return a live count of online proxies in the IPRoyal pool for each country.