Aluvia MCP Server

Most browser automation work still happens through a UI a human drives. Aluvia MCP server moves it into the conversation instead. The Aluvia MCP server exposes browser session management, geo-targeting, and account operations as Model Context Protocol tools for AI agents.

The short version

This repository is organized as a monorepo with three packages:

• CLI for browser automation — — launch headless Chromium sessions from the command line, with JSON output designed for AI agent frameworks
• Automatic block detection and unblocking — — the SDK detects 403s, WAF challenges, and CAPTCHAs, then reroutes through Aluvia and reloads the page automatically
• Smart routing — — proxy only the sites that block you; everything else goes direct to save cost and latency
• Runtime rule updates — — add hostnames to proxy rules on the fly, no restarts or redeployments
• Adapters for every tool — — Playwright, Puppeteer, Selenium, Axios, got, and Node's fetch
• IP rotation and geo targeting — — rotate IPs or target specific US regions at runtime

Getting it running

Installation goes through your MCP client rather than a global install: point it at @aluvia/sdk on npm and it is fetched when the client starts. The copy-paste blocks for Claude Desktop, Claude Code and Cursor are further down this page.

The tools it exposes

The server publishes 3 tools. What each one is for:

• Examples — // Proxy specific hosts only await client.updateRules(["target-site.com", "*.google.com"]);
• Endpoints — The Endpoints tool exposed by this server
• Example — const api = new AluviaApi({ apiKey: process.env.ALUVIA_API_KEY! });

What it needs from you

Configuration is passed through the environment: ALUVIA_API_KEY. Treat anything key-shaped as a real credential — scope it to the minimum the server needs, and rotate it if it ever lands in a shared config.

Things to watch

• It runs with your machine's permissions. That is convenient and also the reason to think about what you point it at before you approve a tool call.
• Missing credentials fail quietly in some clients — if no tools show up, check the environment block first.
• Keep per-call confirmation enabled while you learn its behaviour; it is the cheapest safeguard you have.

How it compares

Among the browser automation options, the useful question is rarely "what can it do" but "what does it cost you to run" — permissions, credentials, and how much of your context its toolset consumes. Aluvia's toolset — Examples, Endpoints, Example — is a fair guide to whether it matches your workflow.

This entry was verified against Aluvia's own documentation before publication; SyncDev keeps the directory reviewed rather than auto-generated.