SlimAtlas AI

Features

• Browser Automation: Navigate, click, type, fill forms, and evaluate JavaScript

• Lightweight by Default: 16x less memory than Chrome, 9x faster execution

• Page Snapshots: Get compact YAML accessibility tree snapshots with unique node IDs for precise element targeting

• LLM-Optimized Context: Snapshots are stripped to semantic essentials, keeping context usage tiny so you can fit more pages and longer sessions into the same window

• Configurable Fallback Browser: Two-level model — lightweight browser first, then escalate to headful Chrome, Browserless or Browserbase cloud browsers only when the default is bot-detected, crashes, or times out.

• Rate Limiting: Stay under the radar. Enforce a configurable minimum delay between requests to specific domains with wildcard patterns (*, *.reddit.com) plus optional jitter, so your agent paces itself instead of hammering a site and tripping its bot defenses.

• Proxy Support: Route every request through an HTTP proxy with a single PROXY_SERVER setting — applied automatically to both browser layers, so your real IP never touches the target. Supports inline basic auth (http://user:pass@host:port).

• Robust Session Management: Per-session serialization, optional session cap (MAX_SESSIONS), mid-session crash recovery with history replay, and graceful shutdown.

• Session Management: Reuse sessions across multiple operations with unique session IDs

• Cross-Platform: Works on Linux and macOS, with a configurable real-browser fallback when needed

Related MCP server: Playwright MCP

Installation

# Install dependencies
npm install

Browser binary is downloaded automatically on first run.

Fallback browser: Level 1 is always the lightweight browser. Level 2 is FALLBACK_BROWSER — one of headful (headful Chrome), browserbase (cloud), browserless (cloud), or none (default, no fallback). When the default crashes, times out, or is bot-detected, the session switches once to the configured fallback. Chrome is bundled by Puppeteer; Browserbase/Browserless require API credentials (see below).

Usage

Run the MCP Server

# Standalone HTTP server (default)
npm run start -- --port=8080

# Remote, authenticated
MCP_AUTH_TOKEN=s3cret npm start -- --host=0.0.0.0 --port=8080

SlimAtlas exposes a single Streamable HTTP /mcp endpoint. Each client gets its own session via the mcp-session-id header; MAX_SESSIONS bounds concurrency. Point your MCP client at it:

{
  "mcpServers": {
    "slimatlas": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

With authentication:

{
  "mcpServers": {
    "slimatlas": {
      "url": "http://your-host:8080/mcp",
      "transport": "http",
      "headers": { "Authorization": "Bearer s3cret" }
    }
  }
}

Tip: Use --host=0.0.0.0 to expose remotely, but always set MCP_AUTH_TOKEN when doing so.

Docker

The image bundles the Lightpanda binary at build time, so the container starts self-contained and never re-downloads:

docker build -t slimatlas .
docker run -p 8080:8080 -e MCP_AUTH_TOKEN=s3cret slimatlas
# -> http://localhost:8080/mcp

Pin a Lightpanda release for reproducible builds (any lightpanda-io/browser tag — default nightly):

docker build --build-arg LIGHTPANDA_VERSION=0.3.3 -t slimatlas:0.3.3 .

Multi-arch is handled automatically — the build detects the container's arch via uname -m (x86_64 → lightpanda-x86_64-linux, aarch64 → lightpanda-aarch64-linux), so the binary always matches the platform being built.

Apple Silicon (M-series Macs): pass --platform linux/arm64 to build/run natively. Without it, Docker Desktop may default to amd64 and run the container under Rosetta, which fails to launch the Lightpanda binary (rosetta error: failed to open elf …).

docker build --platform linux/arm64 -t slimatlas .
docker run --platform linux/arm64 -p 8080:8080 -e MCP_AUTH_TOKEN=s3cret slimatlas

Headful fallback variant. The default image runs Lightpanda only (FALLBACK_BROWSER=none). To enable the headful Chrome fallback (needed only if you set FALLBACK_BROWSER=headful at runtime), build the headful variant — it adds the Chrome runtime libraries + Xvfb (~150MB) and presets FALLBACK_BROWSER=headful:

docker build --build-arg FALLBACK_BROWSER=headful -t slimatlas:headful .
docker run -p 8080:8080 -e MCP_AUTH_TOKEN=s3cret slimatlas:headful

Xvfb is started lazily inside the container on the first session that escalates to headful Chrome — no entrypoint or manual xvfb-run needed.

Stdio Mode

For MCP clients that spawn the server as a subprocess (local, single-client), use stdio transport:

npx tsx src/index.ts

{
  "mcpServers": {
    "slimatlas": {
      "command": "npx",
      "args": ["tsx", "path/to/mcp/src/index.ts"]
    }
  }
}

Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "slimatlas": {
      "command": "npx",
      "args": ["tsx", "path/to/mcp/src/index.ts"]
    }
  }
}

Tip: Set FALLBACK_BROWSER=none to use the lightweight browser only and propagate errors honestly. Use headful or browserbase to enable a real-browser fallback.

See docs/configs.md for all environment variables and CLI flags.

Fallback browser

Skip the default browser for known-hard domains with SKIP_LIGHTPANDA_DOMAINS (comma-separated, subdomain-aware). Matched hosts start directly on the fallback browser. Requires FALLBACK_BROWSER != none (otherwise the list is ignored with a warning).

Rate limiting

Polite, anti-detection pacing for your agent. RateLimiter enforces a server-wide minimum delay between browser_navigate calls to the domains you list, with optional random jitter so the cadence isn't a fixed, fingerprintable interval. Buckets are keyed per host across all sessions (because the target site sees your IP, not your sessions), and patterns support wildcards:

Disabled by default. Enable with a non-empty domain list and a non-zero delay:

# Via CLI flags
npx tsx src/index.ts --rate-limit-domains=*.reddit.com,g2.com --rate-limit-min-delay-ms=2000 --rate-limit-jitter-ms=1500

# Or via environment / .env
RATE_LIMIT_DOMAINS=*.reddit.com,g2.com
RATE_LIMIT_MIN_DELAY_MS=2000
RATE_LIMIT_JITTER_MS=1500

Proxy

Keep your real IP off the target. Set a single PROXY_SERVER and SlimAtlas routes all HTTP traffic from both browser layers through it — no per-browser wiring needed:

• Lightweight browser (level 1) — forwarded via its native --http-proxy flag.

• Chrome fallback (level 2) — applied via --proxy-server at launch.

# Via CLI flag
npx tsx src/index.ts --proxy-server=http://host:8080

# Or via environment / .env
PROXY_SERVER=http://user:pass@host:8080

Inline basic auth (http://user:pass@host:port) is supported on the lightweight browser layer. For IP-allowlisted proxies (no credentials) it just works on both layers. (Per-page Chrome authentication via page.authenticate is on the roadmap.)

CLI Flags

Every environment variable can also be passed as a lower-case CLI flag in --flag=value form. CLI flags override environment variables. Unknown flags cause the server to exit at startup. See docs/configs.md for the full list.

npx tsx src/index.ts --fallback-browser=headful --lightpanda-pool-size=3 --skip-lightpanda-domains=g2.com --navigate-timeout=60000

To use flags from an MCP client, append them to the args array:

{
  "mcpServers": {
    "slimatlas": {
      "command": "npx",
      "args": [
        "tsx",
        "path/to/mcp/src/index.ts",
        "--fallback-browser=headful",
        "--skip-lightpanda-domains=g2.com,linkedin.com",
        "--chrome-pool-size=3"
      ]
    }
  }
}

Usage Workflow

# Example: Navigate, snapshot, and interact with a page

# 1. Navigate to a URL (creates a new session automatically)
result = mcp.call("browser_navigate", {"url": "https://example.com"})
# Returns: session_id: abc1, result: Navigated to https://example.com. Title: Example Domain

# 2. Take a snapshot to see the page structure
snapshot = mcp.call("browser_snapshot", {"session_id": "abc1"})
# Returns YAML with node IDs like: 0: {type: div, children: ...}

# 3. Click a node by ID (from the snapshot)
mcp.call("browser_click", {"session_id": "abc1", "nodeId": 2})

# 4. Type into a search box
mcp.call("browser_type", {"session_id": "abc1", "nodeId": 5, "text": "search query"})

# 5. Close the session when done
mcp.call("browser_close", {"session_id": "abc1"})

Available Tools

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npx vitest

Requirements

• Node.js 18+

• Linux or macOS (downloads automatically) or Chrome/Chromium (fallback)

License

MIT