Skip to main content
Glama

Specillum

English | 한국어 | 日本語 | 简体中文 | Español

Isolated browser pods for AI agents, inside your own logged-in Chrome.

Specillum is an open-source MCP server that lets AI agents such as Claude Code, OpenAI Codex and Cursor browse the web with your real logins, while giving every agent its own private browser window (a "pod"). Agents never see or touch your tabs, and they never step on each other.

Specillum is Latin for probe. From a single shared station, each agent goes out as its own probe.

License: Apache-2.0 MCP

If Specillum is useful to you, please star the repo. It helps other people find it.


Why

Most browser tools for agents give you one of two things:

  • A fresh headless browser with no logins, so the agent hits sign-in walls everywhere.

  • Your real browser, where every agent shares the same tabs. They interfere with each other and with you.

Specillum keeps both benefits:

Fresh browser (e.g. default Playwright MCP)

Your browser, shared

Specillum

Uses your live logins

No

Yes

Yes

Each agent has its own space

Yes

No

Yes

Agents can't reach your tabs

Yes

No

Yes

You can watch and take over

Headed only

Yes

Yes

Several agents at once

Separate browsers

Collisions

One browser, one pod each

Related MCP server: Umbra MCP Server

How it works

                 ┌──────────────── Station: one real Chrome, dedicated profile ────────────────┐
                 │  logins and cookies are shared, live                                         │
                 │                                                                              │
 Claude Code ──► │  Pod "claude-code-x1"  (own window: its tabs and popups only)                │
 Codex ───────►  │  Pod "codex-k9"        (own window)                                          │
 Cursor ──────►  │  Pod "cursor-p3"       (own window)                                          │
                 │                                                                              │
 You ─────────►  │  your own windows: no agent can list or touch them                           │
                 └──────────────────────────────────────────────────────────────────────────────┘
  • Station: One Chrome (or Edge/Chromium) runs with a dedicated Specillum profile and a debugging port bound to 127.0.0.1. You log in there once.

  • Pod: Every MCP connection gets its own Chrome window. Every tool works only on pages the pod opened itself, plus popups those pages open. Nothing exists to list or reach other pages.

  • Cleanup: When an agent disconnects, its pod window closes. Your logins stay.

  • Token-efficient snapshots: The page is summarized as visible interactive elements, one line each, with short refs:

title: Sign in · Example
url: https://example.com/login
headings:
  h1: Welcome back
elements:
[e1] textbox "Email"
[e2] textbox:password "Password"
[e3] button "Sign in"
[e4] link "Forgot password?" -> /reset

Quick start

Requirements: Node.js 20+ and Google Chrome (Microsoft Edge and Chromium also work).

1. Log in once

npx -y specillum open

This opens the Specillum station. Log in to the sites your agents should use. Logins persist in the Specillum profile, separate from your everyday Chrome profile.

2. Add Specillum to your agent

Claude Code

claude mcp add specillum -- npx -y specillum

On Windows, if npx is not found, use claude mcp add specillum -- cmd /c npx -y specillum.

OpenAI Codex (~/.codex/config.toml)

[mcp_servers.specillum]
command = "npx"
args = ["-y", "specillum"]

Cursor (~/.cursor/mcp.json) and other MCP clients

{
  "mcpServers": {
    "specillum": { "command": "npx", "args": ["-y", "specillum"] }
  }
}

3. Use it

Ask your agent to do something on the web, for example: "Check my open GitHub notifications and summarize them." A new pod window appears, and you can watch it work or click in to take over.

Tools

Tool

What it does

pod_status

This agent's pod label and its tabs

pod_window

Show this pod's window to the user, or minimize it to the taskbar

navigate

Open a URL in the active tab

history

Back / forward

snapshot

Compact view of the page with element refs ([e12]) (iframes included). match finds one element, changes returns only what changed

read

Page text as plain text (main content by default)

network

JSON responses this pod's tabs received (fetch/XHR), read-only

response

One response's JSON body, redacted and size-capped; path picks a part

page_data

Data the page embeds: JSON-LD, __NEXT_DATA__, JSON script tags

click

Click by ref; if something covers the element, the error names it

type

Fill an input by ref, optionally press Enter

press

Keyboard key or shortcut

select

Choose <select> options

hover

Hover by ref

drag

Drag one element onto another by ref

upload

Attach local files to a file input or file picker

pdf

Save the active tab as a PDF file

har

Record this pod's requests to a HAR file, with no bodies and secrets masked

scroll

Scroll by screens, or scroll a ref into view

wait

Wait for text to appear or go away, for the URL to change, or a fixed time

screenshot

JPEG of the active tab; annotate labels elements with their refs

dialog

Accept or dismiss the next confirm / prompt dialog (alerts are accepted, confirms dismissed by default)

tabs

List, open, switch, or close tabs of this pod only

console

Console messages and uncaught errors from this pod's tabs

mock

Give this pod's tabs a fake answer to matching requests

evaluate

Run a JavaScript expression in the active tab

storage

Active tab's cookies and web storage; cookie values are never shown (storage group only)

recipe

Save, list, show, run or delete a series of steps for one site

Action tools accept snapshot: true to return a fresh snapshot in the same call, or snapshot: "changes" for only what changed. Tool results also report downloads.

Recipes let an agent repeat a task without reading the page again. Steps find elements by the role and name the snapshot prints, in any iframe, so they survive layout changes. A run stops at the first step that fails, including an expect step whose text never appears, and returns the page so the agent can fix the recipe:

{
  "action": "save",
  "name": "place_search",
  "site": "naver.com",
  "params": ["query"],
  "steps": [
    { "do": "goto", "url": "https://map.naver.com/" },
    { "do": "type", "role": "combobox", "name": "네이버지도 검색", "text": "{query}", "submit": true },
    { "do": "expect", "text": "{query}" }
  ]
}

Then run it with { "action": "run", "name": "place_search", "values": { "query": "Gwanghwamun" } }. Other steps are click, press and click_at, which takes coordinates for what has no element, such as a map canvas. It must be followed by expect and only runs at the viewport size it was saved with.

Configuration

Variable

Default

Purpose

SPECILLUM_PORT

9333

Station debugging port (localhost only)

SPECILLUM_PROFILE

%LOCALAPPDATA%\specillum\profile (Windows), ~/Library/Application Support/specillum/profile (macOS), ~/.config/specillum/profile (Linux)

Station profile directory

SPECILLUM_CHROME

auto-detected

Browser executable

SPECILLUM_POD

<client>-<random>

Fixed pod label

SPECILLUM_KEEP_POD

unset

Set to 1 to keep the pod window after the agent exits

SPECILLUM_POD_WINDOW

visible

minimized opens the pod window in the taskbar; it keeps working there

SPECILLUM_HEADLESS

unset

Set to 1 to run the station with no windows. You cannot watch or log in, and sites can tell it is headless. specillum open always shows the browser; close a headless station first

SPECILLUM_TOOLS

all groups

Comma-separated tool groups to add to core: files (upload, pdf, har), data (network, response, page_data), debug (console, mock, evaluate), recipes (recipe), storage (storage). storage is only on when named. Empty means core only

SPECILLUM_WINDOW

1280x900

Pod window size

SPECILLUM_RECIPES

recipes next to the profile directory

Directory for saved recipes

SPECILLUM_ALLOWED_DOMAINS

any site

Comma-separated sites pods may open, subdomains included

SPECILLUM_UPLOAD_DIRS

none

More directories uploads may come from, besides the one the agent runs in

Security model

Read this before you log in to anything important.

  • Separate profile. Specillum never touches your everyday Chrome profile. Only sites you log in to in the station are available to agents. Start with accounts you would be comfortable letting an assistant use.

  • Localhost port. The station listens on 127.0.0.1 only. Any program running on your machine as you could connect to that port while the station is open. Close the station when you are not using it.

  • Isolation is between agents and windows, not between sites. Pods share cookies on purpose. That is how logins work. An agent in its pod can use any site you are logged in to in the station.

  • Prompt injection. Web pages can contain text meant to manipulate agents. Keep the agent's permissions and the station's logins as narrow as the task needs.

  • Limit where pods go. SPECILLUM_ALLOWED_DOMAINS stops a pod's tabs and iframes from opening other sites. List only what the task needs. It is a guard rail, not a security boundary: a redirect to another site is caught only after the request was sent, and a page can still fetch or load resources from elsewhere.

  • Uploads stay near the agent. upload only takes files from the directory the agent runs in, plus SPECILLUM_UPLOAD_DIRS, and follows links before checking. Everything in those directories can be sent to a website.

  • Saved files stay near the agent. pdf and har only write new files inside the directory the agent runs in, and never replace one. HAR files keep no bodies and mask secret-looking headers and query parameters.

  • storage is off unless named. The station's cookies are your logins, shared with every pod. The tool never shows cookie values and only reaches the active tab's site, but deleting a login cookie logs every pod out of that site. Note that evaluate can still read cookies a page can read.

  • Data tools are read-only and redacted. network, response and page_data only read what this pod's own tabs already received. They never return headers, mask secret-looking keys (token, password, session, csrf…) and token-shaped values (JWT, Bearer …, common API key formats), and cap every result. Masking is a safety net, not a guarantee: the agent can still read the page itself.

  • Recipes are shared and stay on their site. Every pod on the station can run a saved recipe, and recipes are plain JSON files on disk, so keep secrets out of their steps. A run stops if the tab leaves the recipe's site, and it refuses to type into password fields.

  • Open source, no telemetry. Specillum itself sends no data anywhere, and every line is in this repository. Chrome keeps its own settings and telemetry as usual.

FAQ

How do I let Claude Code use my logged-in browser? Add Specillum as an MCP server (claude mcp add specillum -- npx -y specillum), run npx specillum open, and log in once. Claude Code then browses in its own pod window with those logins.

Can several AI agents use one browser at the same time without interfering? Yes. That is what Specillum is for. Each MCP connection gets its own pod window. Tabs, focus and history are separate, and an agent cannot list or reach another pod's pages or yours.

Does it work with OpenAI Codex, Cursor, Windsurf or other MCP clients? Yes. Any client that can launch a stdio MCP server can use Specillum.

Does it work on Windows? Yes. It was developed and tested on Windows. macOS and Linux browser paths are built in.

Why not just use my normal Chrome profile? Since Chrome 136, remote debugging is blocked on the default profile for security reasons. A dedicated profile also limits what agents can reach to the logins you chose.

Is Specillum an alternative to agent browsers like ego lite or Vercel agent-browser? It covers the same idea: agents using a real, logged-in browser with separate spaces. It does this as a small, fully open-source MCP server on top of the Chrome you already have, with no custom browser binary.

How is this different from Playwright MCP or chrome-devtools-mcp? Those connect an agent to a browser. Specillum adds the pod layer: a shared logged-in station, one isolated window per agent, and cleanup on disconnect. It uses Playwright under the hood.

Using Specillum in your own project

You are welcome to use, modify and redistribute Specillum, commercially or not, under the Apache License 2.0. The one thing asked in return is credit:

  • Keep the NOTICE file with any copy or derivative work, as the license requires.

  • Mention the project in your README or docs, for example:

    Built on Specillum by Jason (@jasonwpgml).

  • GitHub's "Cite this repository" button uses CITATION.cff.

And if it helped, a star is always appreciated.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md. Run npm test to check two-agent isolation end to end.

License

Apache-2.0 © 2026 Jason (@jasonwpgml). See NOTICE.

Available Tools

17 tools
clickC

Click an element by its snapshot ref.

Inputs: ref (required), button, double, snapshot.

dialogA

Decide how to answer the next JavaScript dialog (confirm, prompt, beforeunload) before the action that triggers it. Without this, alerts are accepted and confirms/prompts are dismissed; tool results report every dialog.

Inputs: action (required), promptText.

evaluateA

Run a JavaScript expression in the active tab and return the JSON result. For reading data the other tools do not expose.

Inputs: expression (required).

historyC

Go back or forward in the active tab's history.

Inputs: direction (required), snapshot.

hoverA

Move the mouse over an element by ref (opens hover menus, tooltips).

Inputs: ref (required), snapshot.

pod_statusA

Show this agent's pod: its label and the tabs it owns. The pod is a private browser window in the shared, logged-in Specillum Chrome. Other agents' pods and the user's own tabs are never visible here.

Inputs: no named parameters.

pod_windowA

Show this pod's window to the user or minimize it to the taskbar, e.g. when the user asks to watch, or when you need them to log in or solve a CAPTCHA.

Inputs: state (required).

pressC

Press a key or shortcut in the active tab, e.g. Enter, Escape, ArrowDown, Control+A.

Inputs: key (required), snapshot.

readB

Read the visible text of the page (main content by default) as plain text.

Inputs: maxChars, selector.

screenshotA

Take a JPEG screenshot of the active tab. Prefer snapshot for reading; use this for visual checks.

Inputs: fullPage.

scrollB

Scroll the page by screens, or scroll an element into view by ref.

Inputs: ref, screens, snapshot, direction.

selectB

Choose option(s) in a element by ref, matching option value or label.

Inputs: ref (required), values (required), snapshot.

snapshotA

Compact text view of the active tab: title, URL, headings, and visible interactive elements tagged with refs like [e12]. Use the refs with click, type, select and hover. Refs expire when you take a new snapshot.

Inputs: maxElements.

tabsB

Manage the tabs of this pod only: list, open a new tab (optionally at a URL), switch to a tab, or close one.

Inputs: action (required), url, index.

typeB

Type text into an input, textarea or contenteditable element by ref. Replaces existing text unless append is true.

Inputs: ref (required), text (required), append, submit, +1 more.

waitC

Wait for text to appear on the page, or for a fixed time.

Inputs: text, seconds, snapshot.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: click/type/select/hover/press are separate interactions, and navigate/history/scroll/wait are non-overlapping. The only mild overlap is among the read-oriented trio (snapshot, read, screenshot), but their descriptions explicitly differentiate interactive refs vs plain text vs visual capture.

    Naming Consistency4/5

    Names use a consistent lowercase style with mostly single-verb entries (navigate, click, type, press, select, hover, scroll, wait, evaluate). The pod_status and pod_window entries deviate slightly by using a namespace prefix, but this is a coherent grouping rather than a conflicting convention.

    Tool Count4/5

    17 tools is slightly above the ideal 3-15 band but reasonable for full browser automation, since each action (navigate, interact, read, wait, dialog, tabs, JS) earns its place. It leans heavy but not bloated.

    Completeness4/5

    The surface covers the browser-automation lifecycle well: navigation, reading (snapshot/read/screenshot), interaction primitives, history, waits, dialogs, tabs, and raw JS eval. Minor gaps exist (no file upload/download or cookie/storage management), but agents can largely work around these.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets AI assistants control your real Chrome browser to perform web tasks like reading pages, taking screenshots, clicking, and typing, using your existing logged-in sessions.
      145
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects AI agents to your existing daily-driver Chrome so they can inspect, extract from, record, and replay workflows across background tabs without stealing cursor focus, breaking 2FA/SSO sessions, or leaking secrets. A deterministic R0–R4 risk firewall gates state-changing and destructive actions behind human approval.
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Lets AI coding tools drive the real Chrome browser you already have open and logged into — navigating, reading pages, clicking, filling forms, capturing screenshots, and inspecting network, console, and storage state. It works through a Chrome extension rather than a remote-debugging port, so no extra debugging prompt appears and nothing else on the machine can hijack your logged-in browser.
      1 npm
      ISC