iatlas-browser

Use your logged-in Chrome as an API

Overview

iatlas-browser turns the Chrome session you already use into a CLI, an MCP server, and a local HTTP runtime.

Instead of launching a fresh headless browser and rebuilding authentication, it works with your real tabs, real cookies, real page state, and real login context through a local daemon and a Chrome extension.

What that means in practice:

use your current browser login state instead of replaying auth
drive authenticated pages from the terminal, MCP clients, or local HTTP calls
inspect network traffic and browser behavior from the same session you actually use
package repeatable site workflows into reusable site adapters
keep the hard browser-sensitive work local, while using miaoda.vip only for the narrower hosted API subset

Typical use cases:

automate websites that do not have usable APIs
query authenticated pages from an AI agent
inspect network calls from real browser traffic
build site-specific adapters on top of your live session
expose browser control through MCP for agent runtimes

First Success In 3 Minutes

Install the local runtime:

curl -fsSL https://miaoda.vip/install.sh | bash

Start the daemon and verify the browser path:

iatlas-browser daemon
iatlas-browser doctor

Run the first commands:

iatlas-browser open https://example.com
iatlas-browser snapshot -i
iatlas-browser get title

If the task depends on your own login state, tabs, or dynamic browser context, start with the local runtime. If the task is a public, server-safe fetch, use the hosted API on https://miaoda.vip.

Verified Status

Verified on March 15, 2026:

hosted API on https://miaoda.vip is live and usable
MCP server starts and responds correctly over stdio
local daemon and extension handshake works
direct browser commands such as open and snapshot work against a real connected browser
local site_run works for adapters that are compatible with page-context execution

This was verified with real end-to-end calls, not just static code review.

Why This Is Different

Most browser automation stacks start from a clean browser.

iatlas-browser starts from the browser you already trust.

That difference matters most when the hard part is not HTML parsing but session continuity:

company dashboards behind login
admin panels and back offices
social platforms with dynamic clients
websites where the current page state matters as much as the raw DOM
agent workflows that need to act inside the same browser context as the user

Core Capabilities

1. Direct browser operations

You can drive tabs and page interactions from the CLI:

iatlas-browser open https://example.com
iatlas-browser snapshot -i
iatlas-browser click @3
iatlas-browser fill @7 "hello world"
iatlas-browser press Enter
iatlas-browser screenshot

2. Authenticated in-browser requests

Need to call the same endpoint your browser session can already reach?

iatlas-browser fetch https://example.com/api/me --json
iatlas-browser eval "document.title"

3. Site adapters

site adapters let you package repeatable website actions as reusable commands:

iatlas-browser site update
iatlas-browser site list
iatlas-browser site twitter/search "browser agent"
iatlas-browser site zhihu/hot
iatlas-browser site youtube/transcript VIDEO_ID

4. Reverse engineering and diagnostics

You can inspect what the browser is doing in real time:

iatlas-browser network requests --with-body --json
iatlas-browser console
iatlas-browser errors
iatlas-browser trace start

5. MCP integration

The project can run as an MCP server so coding agents and tool-using models can call it directly.

Why This Design Exists

Most web automation tools assume one of these models:

a fresh headless browser
extracted cookies
unofficial APIs
HTML scraping

iatlas-browser takes a different path:

use the browser session you already trust
keep actions local on your machine
use Chrome DevTools Protocol for stronger control
expose results in a form that is usable by both humans and agents

This is especially useful for:

websites with hard-to-recreate authentication
tools behind company login
social platforms with dynamic clients
workflows where page state matters as much as raw HTML

Quick Start

One-line install

curl -fsSL https://miaoda.vip/install.sh | bash

This script will:

clone or update the repository into ~/.iatlas-browser/src
install dependencies
build the project
create local iatlas-browser and iatlas-browser-mcp launchers in ~/.local/bin
run iatlas-browser setup

Install from npm

npm install -g iatlas-browser
iatlas-browser setup

Build or download the extension bundle

Option A: use a release build

Download the latest package from Releases
Unzip it locally

Option B: build from source

pnpm install
pnpm build

The unpacked extension output will be in extension/.

Load the extension in Chrome

Open chrome://extensions/
Enable Developer mode
Click Load unpacked
Select either:
- ~/.iatlas-browser/extension after iatlas-browser setup
- or the local repo extension/ directory if building from source

Important:

automated --load-extension startup is blocked by branded Google Chrome on some machines
manual loading via chrome://extensions/ always works
for isolated automated testing, prefer Chromium or Chrome for Testing instead of the normal Google Chrome app

Extensionless direct CDP subset

If Chrome is launched with remote debugging enabled, iatlas-browser can now run a stronger local subset even when the extension is not connected.

Start Chrome with:

--remote-debugging-port=9222

Supported direct-CDP commands today:

open
snapshot
click
hover
fill
type
eval
get url
get title
get text
screenshot
tab
tab new
tab select
tab close

Important:

this is a fallback path for lower-friction local use
snapshot works in direct mode for page inspection, including --interactive, --compact, --depth, and --selector
direct-CDP snapshot refs are now persisted by the daemon, so later CLI or MCP calls can reuse them for click, hover, fill, type, and get text
adapter commands and richer browser instrumentation still need the extension path
iatlas-browser doctor now detects common Chrome-family browsers such as Chrome, Canary, Chromium, Brave, and Arc, and prints remote-debugging launch hints
iatlas-browser doctor will show whether direct CDP fallback is available

Start the daemon

iatlas-browser daemon

In another terminal, verify the local setup:

iatlas-browser doctor

Expected healthy output:

daemon reachable: OK
extension connected: OK

If extension connected is NO, MCP browser tools and local /command execution will fail until the extension is attached.

First commands

iatlas-browser open https://example.com
iatlas-browser snapshot -i
iatlas-browser get title

MCP Setup

Fastest path:

iatlas-browser mcp-config cursor

That prints a ready-to-paste MCP block.

Default generated snippet files after iatlas-browser setup:

~/.iatlas-browser/mcp/generic.json
~/.iatlas-browser/mcp/cursor.json
~/.iatlas-browser/mcp/claude-desktop.json

Example configuration:

{
  "mcpServers": {
    "iatlas-browser": {
      "command": "npx",
      "args": ["-y", "iatlas-browser", "--mcp"]
    }
  }
}

To verify MCP end to end after setup:

start the daemon with iatlas-browser daemon
confirm iatlas-browser doctor shows extension connected: OK
connect your MCP client using the generated config
run site_list or browser_snapshot

The project has been verified with the official MCP SDK client against the built stdio server.

Local API Setup

The daemon is also a local HTTP API.

Fastest path:

iatlas-browser api-guide

That prints ready-made curl examples for:

GET /status
POST /command

Generated example file after iatlas-browser setup:

~/.iatlas-browser/api/examples.sh

Hosted public API:

docs page: https://miaoda.vip/openapi/
docs endpoint: https://miaoda.vip/v1/docs
registration: POST https://miaoda.vip/v1/register
usage: GET https://miaoda.vip/v1/usage
browser open: POST https://miaoda.vip/v1/open
hosted sites: GET https://miaoda.vip/v1/sites/hosted
hosted site execution: POST https://miaoda.vip/v1/sites/run

Command Groups

Main command families:

navigation: open, back, forward, refresh, close
interaction: click, hover, fill, type, press, check, select
inspection: snapshot, get, screenshot, eval
browser state: tab, frame, dialog, wait
debugging: network, console, errors, trace
platform: daemon, status, stop, reload, doctor, setup, mcp-config, api-guide
adapters: site, guide

Run help at any time:

iatlas-browser --help
iatlas-browser site --help
iatlas-browser mcp-config cursor
iatlas-browser api-guide

Site Adapter System

site is the project’s higher-level workflow layer.

An adapter is a small JavaScript unit that runs against a real website context and turns one web task into one command. Adapters can be:

private and stored locally
pulled from the shared community adapter collection

Default directories:

private adapters: ~/.iatlas-browser/sites
shared adapters: ~/.iatlas-browser/bb-sites from miounet11/lao-s

Useful commands:

iatlas-browser site update
iatlas-browser site search github
iatlas-browser site run github/issues owner/repo

Adapter behavior note:

site_run being available does not mean every adapter will succeed on every site
some adapters work cleanly in page context, such as wikipedia/summary and duckduckgo/search
some adapters may fail because the target site blocks or alters browser-context fetch behavior
hosted adapters on miaoda.vip are separately curated for server-safe execution

To create a new adapter:

iatlas-browser guide

How It Works Internally

The system has four runtime layers:

CLI / MCP client
    ↓
Local daemon (HTTP)
    ↓
Chrome extension (SSE + command execution)
    ↓
Chrome / current user session

More specifically:

the CLI or MCP server creates a structured request
the daemon receives it on a local HTTP endpoint
the extension stays connected to the daemon via SSE
the extension executes the action through Chrome APIs and CDP
the result is sent back to the daemon and returned to the caller

The current implementation also uses accessibility-tree snapshots so the page structure is easier for agents to reason about than raw HTML.

Operational Notes

Use `127.0.0.1`

The project defaults to 127.0.0.1:19824 for local communication. This avoids common localhost IPv4/IPv6 issues in some environments.

Multi-tab isolation

Many commands support --tab <id> so concurrent workflows can target a specific tab safely.

MV3 lifecycle

Chrome Manifest V3 service workers can sleep. The extension includes reconnect and keepalive behavior, but if something looks wrong, run:

iatlas-browser doctor

Browser choice for local verification

For manual day-to-day usage, normal Chrome is fine once the unpacked extension is loaded.

For automated local verification from a clean profile:

prefer Chromium
or use Chrome for Testing
avoid relying on branded Google Chrome startup flags for unpacked extension injection

This matters because some Chrome builds ignore --load-extension, which can make automation look broken even when the daemon, MCP server, and extension code are correct.

Verification Checklist

Minimal local acceptance test:

iatlas-browser doctor
iatlas-browser open https://example.com
iatlas-browser tab
iatlas-browser snapshot -i --tab <tabId>
iatlas-browser site run wikipedia/summary "Node.js" --json
iatlas-browser site run duckduckgo/search "mcp browser" --json

Minimal hosted acceptance test:

curl -s https://miaoda.vip/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com"}'

curl -s https://miaoda.vip/v1/open \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","mode":"metadata"}'

curl -s https://miaoda.vip/v1/sites/run \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name":"github/repo","args":{"repo":"miounet11/lao"}}'

Development

From the repository root:

pnpm install
pnpm build

Key packages:

packages/shared
packages/cli
packages/daemon
packages/extension
packages/mcp

Internal engineering notes:

docs/iatlas-browser-architecture-and-iteration-guide.md
docs/runtime-verification-and-release-checklist.md

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 122 Commits
config		config
content		content
docs		docs
packages		packages
scripts		scripts
skills/iatlas-browser		skills/iatlas-browser
web		web
.gitignore		.gitignore
LICENSE		LICENSE
PRIVACY.md		PRIVACY.md
README.md		README.md
README.zh-CN.md		README.zh-CN.md
install.sh		install.sh
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
tsup.config.ts		tsup.config.ts
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

iatlas-browser

Overview

First Success In 3 Minutes

Verified Status

Why This Is Different

Core Capabilities

1. Direct browser operations

2. Authenticated in-browser requests

3. Site adapters

4. Reverse engineering and diagnostics

5. MCP integration

Why This Design Exists

Quick Start

One-line install

Install from npm

Build or download the extension bundle

Load the extension in Chrome

Extensionless direct CDP subset

Start the daemon

First commands

MCP Setup

Local API Setup

Command Groups

Site Adapter System

How It Works Internally

Operational Notes

Use 127.0.0.1

Multi-tab isolation

MV3 lifecycle

Browser choice for local verification

Verification Checklist

Development

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Use `127.0.0.1`

Packages