Oya Browser MCP server

OpenRouter for browsers.

One API over Oya Cloud, Browserbase, Steel, Anchor, Browser Use and your own Chrome. Turn a portal task into a reusable playbook. Replay with new inputs, review agent repairs, and bring in a person when a run needs help.

Hosted · Self-host · Docs · Examples

Three real browsers on a self-hosted stack: live view, a human takeover, numbered elements, and the hand-back. Nothing mocked (scripts/record-walkthrough.mjs).

⚡ Quick start

npm install @oya-ai/browser

Set OYAAPIKEY from browser.getoya.ai. The SDK supports Node.js 18+; this example uses ES modules.

import { Oya } from "@oya-ai/browser";

const oya = new Oya(); // Reads OYA_API_KEY; optional OYA_BASE_URL for self-hosting.
const browser = await oya.browser.start({ captcha: "auto" });
try {
  await browser.goto("https://example.com");
  console.log(await browser.ask("What is the main heading?"));
} finally {
  await browser.stop();
}

Choose the provider in your key settings or pass provider to start(). On Node.js 24+, await using browser = await oya.browser.start() handles cleanup automatically.

Portal automation: record once, replay with new inputs

Adapted from the portal-automation project, with a fictional request and environment-based credentials. Set PORTALURL, PORTALUSERNAME, and PORTAL_PASSWORD to your test portal and adapt the instructions to its pages. Save this as portal.mjs and run node portal.mjs.

import { createInterface } from "node:readline/promises";
import { Oya } from "@oya-ai/browser";

function requiredEnv(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running.`);
  return value;
}

const oya = new Oya({ apiKey: requiredEnv("OYA_API_KEY") });
const portalUrl = requiredEnv("PORTAL_URL");
const name = "portal-request-review";
const data = { customerName: "Alex Example", requestId: "DEMO-0001" };
const secrets = {
  username: requiredEnv("PORTAL_USERNAME"),
  password: requiredEnv("PORTAL_PASSWORD"),
};
const persona = (await oya.personas.list()).find((p) => p.name === "portal-demo")
  ?? await oya.personas.create({ name: "portal-demo" });
const browser = await oya.browser.start({ persona: persona.id, captcha: "auto" });

Shortened. The full README is on GitHub.