@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).

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

Account Tools

Geo Tools

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

Use Cases

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

→ Agent calls session_start with autoUnblock: true, then session_set_geo with geo: "us" 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 countries (e.g. us, gb, de) for localized content
• Runtime updates — Add rules, rotate IPs, change geo without restarting

Links

Dependencies

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

License

MIT

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.