{"_id":"@aluvia/mcp","_rev":"9-fd46512d926c4fd94015727971ac2cca","name":"@aluvia/mcp","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@aluvia/mcp","version":"1.0.0","author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/mcp@1.0.0","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"bin":{"aluvia-mcp":"dist/esm/mcp-server.js"},"dist":{"shasum":"a285bb28eb9ab6cd6446b0d59598c0e14901da65","tarball":"https://registry.npmjs.org/@aluvia/mcp/-/mcp-1.0.0.tgz","fileCount":6,"integrity":"sha512-IBwFeqxjolQZ7Ek9u06ozFXOa5SF8rgq/rfZmPBiXFcRO9WAyamHyrKyao7bIakAmZA2jz11I+75zz1zK5hzXw==","signatures":[{"sig":"MEQCIA20tmvb0VpZfXQtA3Bifb7QPNPBpbzbzBr4vsncWsqFAiAAnJxUa/oqJlo16esXRNCl8kHVRKsqv0Xxa/rfLpysbw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":28618},"main":"./dist/esm/mcp-server.js","type":"module","engines":{"node":">=18"},"gitHead":"ce6fbd3e1f92e39e837f39a53b1c1584169ecb17","scripts":{"build":"tsc -p tsconfig.json"},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","_npmVersion":"11.8.0","description":"Aluvia MCP server — Model Context Protocol tools for browser sessions and account","directories":{},"_nodeVersion":"22.21.0","dependencies":{"zod":"^3.23.8","@aluvia/sdk":"^1.4.0","@modelcontextprotocol/sdk":"^1.26.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.0_1770972433875_0.47114419672981667","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@aluvia/mcp","version":"1.0.1","keywords":["mcp","model-context-protocol","ai-agent","browser-automation","playwright","proxy","anti-bot","claude"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/mcp@1.0.1","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"bin":{"aluvia-mcp":"dist/esm/mcp-server.js"},"dist":{"shasum":"8acc06cf29531d7f6e4b0b0f63146533097e6fad","tarball":"https://registry.npmjs.org/@aluvia/mcp/-/mcp-1.0.1.tgz","fileCount":4,"integrity":"sha512-n3O/aAXJH9iDdI47HYEEJUGnVk2+vq6ozWDulub38ydxElsv29Iy/R7Y0vtNZ7Yw2PJs/IWFwKlEaPzC2BL/9Q==","signatures":[{"sig":"MEYCIQDlBtbXRURWL785eGLxfXEzMzPj+k3iG0I26x4OZ62ihQIhAN3SaxxOHdxf+tdalTlIbCIpmphLTE3YqJMfQHftZKBC","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19680},"main":"./dist/esm/mcp-server.js","type":"module","engines":{"node":">=18"},"gitHead":"0491172aecf5ce552e1ce2941275e2f4ad6f3f12","scripts":{"build":"tsc -p tsconfig.json"},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","_npmVersion":"11.10.0","description":"Aluvia MCP server — Model Context Protocol tools for browser sessions and account","directories":{},"_nodeVersion":"20.19.6","dependencies":{"zod":"^3.23.8","@aluvia/sdk":"^1.4.1","@modelcontextprotocol/sdk":"^1.26.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.1_1771487956404_0.5838177671728402","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@aluvia/mcp","version":"1.0.2","keywords":["mcp","model-context-protocol","ai-agent","browser-automation","playwright","proxy","anti-bot","claude"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/mcp@1.0.2","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"bin":{"aluvia-mcp":"dist/esm/mcp-server.js"},"dist":{"shasum":"48ad01d51d508ee924abd432a1179780f204db7f","tarball":"https://registry.npmjs.org/@aluvia/mcp/-/mcp-1.0.2.tgz","fileCount":6,"integrity":"sha512-dLEx3saqvgXNMxqumCrskaeMEfLH3JoiKJpWEU6HNwQeq1dZ9RK5W/vFmL1WZb+6i7XkskhJQ/hbG8sr6WJPcQ==","signatures":[{"sig":"MEYCIQDDgi5yKSO/XxwLQcYQRTDoDINRW4t+1cwq3PTUOMJNNAIhAL+fnosufU6VjAdtWgJjjR/2G5ESsF5+PX5Qo/4MNePn","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29612},"main":"./dist/esm/mcp-server.js","type":"module","engines":{"node":">=18"},"gitHead":"762ca4dc9cb23a46fb29ee475af873dd93cb7552","scripts":{"test":"node test-stdio.mjs","build":"tsc -p tsconfig.json"},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","_npmVersion":"11.8.0","description":"Aluvia MCP server — Model Context Protocol tools for browser sessions and account","directories":{},"_nodeVersion":"22.21.0","dependencies":{"zod":"^3.23.8","@aluvia/cli":"^1.0.0","@aluvia/sdk":"^2.0.0","@modelcontextprotocol/sdk":"^1.26.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.2_1771812756370_0.15451943727434148","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@aluvia/mcp","version":"1.0.3","keywords":["mcp","model-context-protocol","ai-agent","browser-automation","playwright","proxy","anti-bot","claude"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/mcp@1.0.3","maintainers":[{"name":"denniskrol","email":"dennis@xtrella.com"}],"bin":{"aluvia-mcp":"dist/esm/mcp-server.js"},"dist":{"shasum":"1dfea2a8826540f0fbaa92bef40bf08dfde0bebf","tarball":"https://registry.npmjs.org/@aluvia/mcp/-/mcp-1.0.3.tgz","fileCount":6,"integrity":"sha512-3A/yMVYru3Bb9pjeVJohCr7/vzZYZsnz6Es+Eul49OxUufRNflPbKAfLPWEgNv9nxlSIANOZ2Yey0J2YNIIxXQ==","signatures":[{"sig":"MEUCIFfobiQAiUjdH88a2QICXLJqu2OK9sSNDrxFgCoeO062AiEAv3owN02oKjow5nQitPu1bjugOS3DdzZh884OnkbHt0w=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":29600},"main":"./dist/esm/mcp-server.js","type":"module","engines":{"node":">=18"},"gitHead":"745cc8cb3050c77c21452b02aed096232c7ac3af","scripts":{"test":"node test-stdio.mjs","build":"tsc -p tsconfig.json"},"_npmUser":{"name":"denniskrol","email":"dennis@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","_npmVersion":"11.8.0","description":"Aluvia MCP server — Model Context Protocol tools for browser sessions and account","directories":{},"_nodeVersion":"22.21.0","dependencies":{"zod":"^3.23.8","@aluvia/cli":"^1.0.0","@aluvia/sdk":"^2.0.0","@modelcontextprotocol/sdk":"^1.26.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.3_1773629414365_0.2826973502355634","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@aluvia/mcp","version":"1.0.4","keywords":["mcp","model-context-protocol","ai-agent","browser-automation","playwright","proxy","anti-bot","claude"],"author":{"name":"Aluvia"},"license":"MIT","_id":"@aluvia/mcp@1.0.4","maintainers":[{"name":"herbertxtrella","email":"herbert@xtrella.com"},{"name":"denniskrol","email":"dennis@xtrella.com"}],"bin":{"aluvia-mcp":"dist/esm/mcp-server.js"},"dist":{"shasum":"18e0185094bc7c76952672e0c629ea0847f967d2","tarball":"https://registry.npmjs.org/@aluvia/mcp/-/mcp-1.0.4.tgz","fileCount":6,"integrity":"sha512-dNhaaLmbwuCG+cIGe6gERaH/60C8uxw8uCO9wGB9OS6nM9I0rb5Mxs+d2HVfqi5gPNVj3yMU13sabBsQZopnSQ==","signatures":[{"sig":"MEUCICwyjPX+1DVUcQEwoqr8YwQIaTPlz3/X+B27efS/lI4wAiEApfbeDkR4yiedIVhRkeaMEYL+KkopCV1A5ioByjKVdpU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30396},"main":"./dist/esm/mcp-server.js","type":"module","engines":{"node":">=18"},"gitHead":"ab555069f5983345efe884737916d0db27321796","scripts":{"test":"node test-stdio.mjs","build":"tsc -p tsconfig.json"},"_npmUser":{"name":"herbertxtrella","email":"herbert@xtrella.com"},"deprecated":"Deprecated. Aluvia is a local CLI, not an MCP. Use npx aluvia-cli setup. https://aluvia.io/docs","_npmVersion":"11.13.0","description":"Aluvia MCP server — Model Context Protocol tools for browser sessions and account","directories":{},"_nodeVersion":"24.16.0","dependencies":{"zod":"^3.23.8","@aluvia/cli":"^1.0.0","@aluvia/sdk":"^2.0.0","@modelcontextprotocol/sdk":"^1.26.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"_npmOperationalInternal":{"tmp":"tmp/mcp_1.0.4_1780891137697_0.3459757315311225","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2026-02-13T08:47:13.807Z","modified":"2026-08-31T13:00:34.946Z","1.0.0":"2026-02-13T08:47:14.023Z","1.0.1":"2026-02-19T07:59:16.550Z","1.0.2":"2026-02-23T02:12:36.534Z","1.0.3":"2026-03-16T02:50:14.510Z","1.0.4":"2026-06-08T03:58:57.828Z"},"author":{"name":"Aluvia"},"license":"MIT","keywords":["mcp","model-context-protocol","ai-agent","browser-automation","playwright","proxy","anti-bot","claude"],"description":"Aluvia MCP server — Model Context Protocol tools for browser sessions and account","maintainers":[{"name":"biggyc","email":"chris@xtrella.com"},{"name":"denniskrol","email":"dennis@xtrella.com"},{"name":"herbertxtrella","email":"herbert@xtrella.com"}],"readme":"# @aluvia/mcp\r\n\r\n

\r\n \"Aluvia\r\n

\r\n\r\n

\r\n Unblockable browser automation for AI agents.\r\n

\r\n\r\n

\r\n \"npm\r\n \"npm\r\n \"license\"\r\n \"MCP\r\n

\r\n\r\n---\r\n\r\n**Stop getting blocked.** The Aluvia MCP server exposes browser session management, geo-targeting, and account operations as [Model Context Protocol](https://modelcontextprotocol.io) 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.\r\n\r\n## Table of Contents\r\n\r\n- [Get an Aluvia API Key](#-get-an-aluvia-api-key)\r\n- [Quick Start](#-quick-start)\r\n- [Requirements](#-requirements)\r\n- [Installation](#-installation)\r\n- [Client Configuration](#-client-configuration)\r\n- [Available Tools](#-available-tools)\r\n- [Use Cases](#-use-cases)\r\n- [Why Aluvia](#-why-aluvia)\r\n- [Links](#-links)\r\n- [License](#license)\r\n\r\n---\r\n\r\n## Get an Aluvia API Key\r\n\r\nYou need an API key to run the MCP server. Get one from the [Aluvia dashboard](https://dashboard.aluvia.io):\r\n\r\n1. Sign up or sign in at [dashboard.aluvia.io](https://dashboard.aluvia.io)\r\n2. In your account, open the API & SDKs section\r\n3. Copy your API key\r\n\r\nUse 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).\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n```bash\r\nnpm install @aluvia/mcp\r\nexport ALUVIA_API_KEY=\"your-api-key\"\r\nnpx aluvia-mcp\r\n```\r\n\r\nThe server runs on **stdio** (stdin/stdout JSON-RPC) — MCP clients spawn it and communicate over stdio.\r\n\r\n---\r\n\r\n## Requirements\r\n\r\n- **Node.js** 18+\r\n- **Aluvia API key** — See [Get an Aluvia API Key](#-get-an-aluvia-api-key)\r\n- **Playwright** — Required for session tools (`session_start`, etc.); install with `npm install playwright`\r\n\r\n---\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install @aluvia/mcp\r\n```\r\n\r\nSet your API key in the environment:\r\n\r\n```bash\r\nexport ALUVIA_API_KEY=\"your-api-key\"\r\n```\r\n\r\nOr in a `.env` file (never commit):\r\n\r\n```\r\nALUVIA_API_KEY=your-api-key\r\n```\r\n\r\n---\r\n\r\n## Client Configuration\r\n\r\nAdd the config below for your MCP client. Replace `your-api-key` with your actual key.\r\n\r\n### Claude Desktop\r\n\r\nAdd to `claude_desktop_config.json`:\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"aluvia\": {\r\n \"command\": \"npx\",\r\n \"args\": [\"-y\", \"aluvia-mcp\"],\r\n \"env\": {\r\n \"ALUVIA_API_KEY\": \"your-api-key\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Claude Code\r\n\r\nAdd to `.claude/settings.json` or project MCP config:\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"aluvia\": {\r\n \"command\": \"npx\",\r\n \"args\": [\"-y\", \"aluvia-mcp\"],\r\n \"env\": {\r\n \"ALUVIA_API_KEY\": \"your-api-key\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Cursor\r\n\r\n1. Open **Settings → MCP**\r\n2. Add a new MCP server\r\n3. Use:\r\n - **Command**: `npx`\r\n - **Args**: `[\"-y\", \"aluvia-mcp\"]`\r\n - **Environment variables**: `ALUVIA_API_KEY` = your key\r\n\r\n### VS Code / Cursor (mcp.json)\r\n\r\nFor workspace-level config, add `.vscode/mcp.json` or `mcp.json`:\r\n\r\n```json\r\n{\r\n \"mcpServers\": {\r\n \"aluvia\": {\r\n \"command\": \"npx\",\r\n \"args\": [\"-y\", \"aluvia-mcp\"],\r\n \"env\": {\r\n \"ALUVIA_API_KEY\": \"your-api-key\"\r\n }\r\n }\r\n }\r\n}\r\n```\r\n\r\n### Other MCP Clients\r\n\r\nSpawn with `command: \"npx\"`, `args: [\"-y\", \"aluvia-mcp\"]`, and `ALUVIA_API_KEY` in the process environment. See the [MCP Server Guide](https://github.com/aluvia-connect/sdk-node/blob/main/docs/mcp-server-guide.md#client-configuration) for a Node.js client example.\r\n\r\n---\r\n\r\n## Available Tools\r\n\r\nAll tools return JSON. On success, `isError` is `false`. On failure, `isError` is `true` and the payload includes an `error` field.\r\n\r\n### Session Tools\r\n\r\n| Tool | Description |\r\n| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\r\n| `session_start` | Start a browser session with Aluvia smart proxy. **Params**: `url` (required), `connectionId`, `headful`, `browserSession`, `autoUnblock`, `disableBlockDetection` |\r\n| `session_close` | Close one or all running sessions. **Params**: `browserSession`, `all` |\r\n| `session_list` | List active sessions (PIDs, URLs, CDP URLs, connection IDs) |\r\n| `session_get` | Full session details including block detection state and connection config. **Params**: `browserSession` |\r\n| `session_rotate_ip` | Rotate IP for a session (new session ID). **Params**: `browserSession` |\r\n| `session_set_geo` | Set or clear geo-targeting (e.g. `us`, `gb`, `de`). **Params**: `geo`, `clear`, `browserSession` |\r\n| `session_set_rules` | Append or remove proxy routing rules (comma-separated hostnames). **Params**: `rules`, `remove`, `browserSession` |\r\n\r\n### Account Tools\r\n\r\n| Tool | Description |\r\n| --------------- | ------------------------------------------------------------------------ |\r\n| `account_get` | Account info (balance, plan, connection count) |\r\n| `account_usage` | Usage statistics for a date range. **Params**: `start`, `end` (ISO 8601) |\r\n\r\n### Geo Tools\r\n\r\n| Tool | Description |\r\n| ----------- | ------------------------------------------------------------------------ |\r\n| `geos_list` | List available geo-targeting countries (e.g. `us`, `gb`, `de`) |\r\n\r\nFull parameter and response details: [MCP Server Guide — Tool Reference](https://github.com/aluvia-connect/sdk-node/blob/main/docs/mcp-server-guide.md#tool-reference).\r\n\r\n---\r\n\r\n## Use Cases\r\n\r\n| Scenario | Tools Used | Flow |\r\n| ------------------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------- |\r\n| **Scrape a protected site** | `session_start`, `session_list` | Start with `autoUnblock: true`; agent receives CDP URL for Playwright/Puppeteer |\r\n| **Bypass regional restriction** | `session_start`, `session_set_geo` | Set `geo: \"us\"` to access United States-only content |\r\n| **Recover from block** | `session_rotate_ip`, `session_set_rules` | Rotate IP or add hostname to proxy rules at runtime |\r\n| **Monitor usage** | `account_get`, `account_usage` | Check balance and data consumed |\r\n| **Multi-session automation** | `session_start`, `session_close`, `session_list` | Name sessions via `browserSession`, manage multiple browsers |\r\n\r\n**Example agent prompt:** _\"Open target-site.com. If you get blocked, rotate the IP to a US-based address and try again.\"_\r\n\r\n→ Agent calls `session_start` with `autoUnblock: true`, then `session_set_geo` with `geo: \"us\"` if needed.\r\n\r\n---\r\n\r\n## Why Aluvia\r\n\r\n- **Mobile carrier IPs** — Same IPs real users use; sites trust them\r\n- **Block detection** — Detects 403s, WAF challenges, CAPTCHAs; auto-reloads through Aluvia when blocked\r\n- **Smart routing** — Proxy only hostnames that block you; everything else goes direct (saves cost and latency)\r\n- **Geo-targeting** — Target countries (e.g. `us`, `gb`, `de`) for localized content\r\n- **Runtime updates** — Add rules, rotate IPs, change geo without restarting\r\n\r\n---\r\n\r\n## Links\r\n\r\n| Resource | URL |\r\n| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\r\n| **Aluvia Dashboard** | [dashboard.aluvia.io](https://dashboard.aluvia.io) |\r\n| **npm** | [npmjs.com/package/@aluvia/mcp](https://www.npmjs.com/package/@aluvia/mcp) |\r\n| **Full MCP Guide** | [docs/mcp-server-guide.md](https://github.com/aluvia-connect/sdk-node/blob/main/docs/mcp-server-guide.md) |\r\n| **Aluvia SDK** | [@aluvia/sdk](https://github.com/aluvia-connect/sdk-node) — CLI, adapters, and [quick start](https://github.com/aluvia-connect/sdk-node#quick-start) |\r\n| **MCP Protocol** | [modelcontextprotocol.io](https://modelcontextprotocol.io) |\r\n\r\n---\r\n\r\n## Dependencies\r\n\r\n- **@aluvia/sdk** — CLI handlers and proxy logic. For programmatic use (`AluviaClient`, `connect()`), install the full SDK: `npm install @aluvia/sdk`.\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT\r\n","readmeFilename":"README.md"}