@aluvia/mcp

Stop getting blocked. The Aluvia MCP server exposes browser session management, geo-targeting, and account operations as Model Context Protocol tools for AI agents. Route traffic through premium US mobile carrier IPs and bypass 403s, CAPTCHAs, and WAFs that stop other tools. Works with Claude Desktop, Claude Code, Cursor, VS Code, and any MCP-compatible client.

Table of Contents

• Get an Aluvia API Key
• Quick Start
• Requirements
• Installation
• Client Configuration
• Available Tools
• Use Cases
• Why Aluvia
• Links
• License

Get an Aluvia API Key

You need an API key to run the MCP server. Get one from the Aluvia dashboard:

1. Sign up or sign in at dashboard.aluvia.io
2. In your account, open the API & SDKs section
3. Copy your API key

Use it as an environment variable: export ALUVIA_API_KEY="your-api-key" or add ALUVIA_API_KEY=your-api-key to a .env file (never commit it).

Quick Start

npm install @aluvia/mcp
export ALUVIA_API_KEY="your-api-key"
npx aluvia-mcp

The server runs on stdio (stdin/stdout JSON-RPC) — MCP clients spawn it and communicate over stdio.

Requirements

• Node.js 18+
• Aluvia API key — See Get an Aluvia API Key
• Playwright — Required for session tools (session_start, etc.); install with npm install playwright

Installation

npm install @aluvia/mcp

Set your API key in the environment:

export ALUVIA_API_KEY="your-api-key"

Or in a .env file (never commit):

ALUVIA_API_KEY=your-api-key

Client Configuration

Add the config below for your MCP client. Replace your-api-key with your actual key.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "aluvia": {
      "command": "npx",
      "args": ["-y", "aluvia-mcp"],
      "env": {
        "ALUVIA_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json or project MCP config:

{
  "mcpServers": {
    "aluvia": {
      "command": "npx",
      "args": ["-y", "aluvia-mcp"],
      "env": {
        "ALUVIA_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor

1. Open Settings → MCP
2. Add a new MCP server
3. Use:
   • Command: npx
   • Args: ["-y", "aluvia-mcp"]
   • Environment variables: ALUVIA_API_KEY = your key

VS Code / Cursor (mcp.json)

For workspace-level config, add .vscode/mcp.json or mcp.json:

{
  "mcpServers": {
    "aluvia": {
      "command": "npx",
      "args": ["-y", "aluvia-mcp"],
      "env": {
        "ALUVIA_API_KEY": "your-api-key"
      }
    }
  }
}

Other MCP Clients

Spawn with command: "npx", args: ["-y", "aluvia-mcp"], and ALUVIA_API_KEY in the process environment. See the MCP Server Guide for a Node.js client example.

Available Tools

All tools return JSON. On success, isError is false. On failure, isError is true and the payload includes an error field.

Session Tools

| Tool | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | session_start | Start a browser session with Aluvia smart proxy. Params: url (required), connectionId, headful, browserSession, autoUnblock, disableBlockDetection | | session_close | Close one or all running sessions. Params: browserSession, all | | session_list | List active sessions (PIDs, URLs, CDP URLs, connection IDs) | | session_get | Full session details including block detection state and connection config. Params: browserSession | | session_rotate_ip | Rotate IP for a session (new session ID). Params: browserSession | | session_set_geo | Set or clear geo-targeting (e.g. us, us_ca, us_ny). Params: geo, clear, browserSession | | session_set_rules | Append or remove proxy routing rules (comma-separated hostnames). Params: rules, remove, browserSession |

Account Tools

| Tool | Description | | --------------- | ------------------------------------------------------------------------ | | account_get | Account info (balance, plan, connection count) | | account_usage | Usage statistics for a date range. Params: start, end (ISO 8601) |

Geo Tools

| Tool | Description | | ----------- | ------------------------------------------------------------------------ | | geos_list | List available geo-targeting regions (e.g. us, us_ny, us_ca, gb) |

Full parameter and response details: MCP Server Guide — Tool Reference.

Use Cases

| Scenario | Tools Used | Flow | | ------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- | | Scrape a protected site | session_start, session_list | Start with autoUnblock: true; agent receives CDP URL for Playwright/Puppeteer | | Bypass regional restriction | session_start, session_set_geo | Set geo: "us_ca" to access California-only content | | Recover from block | session_rotate_ip, session_set_rules | Rotate IP or add hostname to proxy rules at runtime | | Monitor usage | account_get, account_usage | Check balance and data consumed | | Multi-session automation | session_start, session_close, session_list | Name sessions via browserSession, manage multiple browsers |

Example agent prompt: "Open target-site.com. If you get blocked, rotate the IP to California and try again."

→ Agent calls session_start with autoUnblock: true, then session_set_geo with geo: "us_ca" if needed.

Why Aluvia

• Mobile carrier IPs — Same IPs real users use; sites trust them
• Block detection — Detects 403s, WAF challenges, CAPTCHAs; auto-reloads through Aluvia when blocked
• Smart routing — Proxy only hostnames that block you; everything else goes direct (saves cost and latency)
• Geo-targeting — Target US regions (e.g. us_ca, us_ny) for localized content
• Runtime updates — Add rules, rotate IPs, change geo without restarting

Links

| Resource | URL | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Aluvia Dashboard | dashboard.aluvia.io | | npm | npmjs.com/package/@aluvia/mcp | | Full MCP Guide | docs/mcp-server-guide.md | | Aluvia SDK | @aluvia/sdk — CLI, adapters, and quick start | | MCP Protocol | modelcontextprotocol.io |

Dependencies

• @aluvia/sdk — CLI handlers and proxy logic. For programmatic use (AluviaClient, connect()), install the full SDK: npm install @aluvia/sdk.

License

MIT