Floppydata MCP

Floppydata MCP lets agents use the Floppydata Client API v2 (Web Data, proxies, and Cloud Browser) directly from an MCP-compatible client.

It is intentionally small: install it with npx, provide FLOPPYDATA_API_KEY, and the server talks to https://api.floppydata.net.

Setup

Create a Client API key in the Floppydata dashboard:

https://app.floppydata.com/api-keys

Add this server to your MCP client:

{
  "mcpServers": {
    "floppydata": {
      "command": "npx",
      "args": ["-y", "@floppydata/mcp"],
      "env": {
        "FLOPPYDATA_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

That is the whole setup. There is no hosted service, no extra CLI, and no base URL configuration.

Tools

fetch_web_data

Fetch a public page through Web Data.

Useful when an agent needs page HTML and the target site should be fetched through Floppydata infrastructure.

Required input:

{
  "url": "https://example.com"
}

Optional inputs: countryCode, city, difficulty, cacheMaxAgeDays.

create_rotating_proxy_connection

Build one rotating proxy connection.

The most important value in the response is:

connection.connectionString

Example input:

{
  "type": "residential",
  "country": "US",
  "city": "New York",
  "rotation": 15,
  "protocol": "http"
}

list_rotating_proxy_locations

List available rotating proxy countries, cities, and states for a proxy type.

Example input:

{
  "type": "residential"
}

check_proxy

Check the exit IP and location for a proxy.

Example input:

{
  "connectionString": "http://USERNAME:[email protected]:10080"
}

The response shape is:

{
  "ip": "123.45.67.89",
  "location": {
    "countryCode": "US",
    "country": "United States",
    "state": "California",
    "city": "San Francisco"
  }
}

list_static_proxies

List static proxies on the account.

Use items[n].connection.connectionString as the copy-paste proxy URL.

get_account_balances

Check account balances across Web Data, rotating proxy traffic, and static proxies.

Optional input:

{
  "product": "proxy-rotating"
}

Allowed products: web-data, proxy-rotating, proxy-static.

get_account_usage

Check account usage rollups.

Responses include:

• yesterday
• last7Days
• last30Days
• optional requestedRange when from or to is provided
• lastUpdatedAt

Example input:

{
  "product": "proxy-rotating",
  "from": "2026-06-01T00:00:00Z",
  "to": "2026-06-26T23:59:59Z",
  "countryCode": "US",
  "proxyType": "residential"
}

Cloud Browser

Start a cloud browser that already has a Floppydata proxy attached, then drive it from your own Puppeteer or Playwright code.

create_browser_session

Creates and starts a browser. The smallest request is {}: a burner browser on a residential proxy that runs for 10 minutes.

The most important value in the response is:

connectUrl

Pass it to puppeteer.connect({ browserWSEndpoint: connectUrl }) or chromium.connectOverCDP(connectUrl).

Example input:

{
  "proxy": {
    "type": "residential",
    "location": { "countryCode": "US", "city": "New York" },
    "rotation": { "mode": "sticky" }
  },
  "browser": {
    "viewport": { "width": 1440, "height": 900 },
    "fingerprint": { "os": "windows", "locale": "en-US", "timezone": "auto" }
  },
  "runtime": { "timeoutSeconds": 1800, "keepAlive": true },
  "persist": { "ttlSeconds": 900 },
  "startUrl": "https://example.com"
}

• Use "proxy": { "type": "static", "ip": "123.45.67.89" } to browse through one of your static IPs from list_static_proxies.
• Add persist.ttlSeconds to keep settings.id reusable after the session ends. Pass "settings": { "id": "..." } on a later call to come back with the same cookies and fingerprint.
• storage.cookies loads cookies before the session starts.

list_browser_sessions

List session history. Optional inputs: status (running, stopped, timedOut, failed), cursor, limit.

get_browser_session

Get one session by sessionId. Returns a freshly signed connectUrl while the session is running.

stop_browser_session

Stop a session by sessionId and save its persistent state. Stop sessions when you are done with them.

create_browser_live_view

Get a liveViewUrl a human can open to watch and control a running session. It is rejected while a Puppeteer or Playwright client is connected.

delete_browser_session

Delete an ended session from history by sessionId. Saved settings are kept.

delete_browser_settings

Permanently delete saved settings and browser state by settingsId.

Security

The server reads the API key from FLOPPYDATA_API_KEY and sends it as X-Api-Key.

API keys and passwords are redacted from errors and logs. Proxy passwords and signed browser connectUrl tokens are still returned in successful responses because those credentials are the output customers need to use. Tokens in error messages are redacted.

Development

See CONTRIBUTING.md.