Specillum
Control a private, logged-in browser pod (an isolated Chrome window) to browse and interact with websites on the user's behalf.
Pod management: check the pod's label and owned tabs (
pod_status), show or minimize its window so the user can watch, log in, or solve a CAPTCHA (pod_window).Navigation: open URLs (
navigate), go back/forward (history), and list/open/switch/close tabs within the pod only (tabs).Reading pages: get compact snapshots of interactive elements with refs (
snapshot), or plain text of the main content or a CSS selector (read).Interacting: click by ref (
click, incl. right/middle/double), fill inputs (type, with optional Enter), press keys/shortcuts (press), choose<select>options (select), hover (hover), scroll (scroll), and wait for text or a fixed time (wait).Dialogs: pre-decide accept/dismiss for the next alert, confirm, prompt or beforeunload (
dialog).Visuals: capture a JPEG screenshot of the active tab (
screenshot).Scripting: run a JavaScript expression in the active tab and get JSON back (
evaluate).Chaining: most action tools accept
snapshot: trueto return a fresh snapshot in the same call.
Provides an MCP server that controls a real Chrome browser with a dedicated profile, giving each AI agent its own isolated browser window (pod) to browse websites using the station's live logins while keeping tabs, focus, and history separate.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Specillum Check my open GitHub notifications and summarize them"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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?" -> /resetQuick start
Requirements: Node.js 20+ and Google Chrome (Microsoft Edge and Chromium also work).
1. Log in once
npx -y specillum openThis 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 specillumOn 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 |
| This agent's pod label and its tabs |
| Show this pod's window to the user, or minimize it to the taskbar |
| Open a URL in the active tab |
| Back / forward |
| Compact view of the page with element refs ( |
| Page text as plain text (main content by default) |
| JSON responses this pod's tabs received (fetch/XHR), read-only |
| One response's JSON body, redacted and size-capped; |
| Data the page embeds: JSON-LD, |
| Click by ref; if something covers the element, the error names it |
| Fill an input by ref, optionally press Enter |
| Keyboard key or shortcut |
| Choose |
| Hover by ref |
| Drag one element onto another by ref |
| Attach local files to a file input or file picker |
| Save the active tab as a PDF file |
| Record this pod's requests to a HAR file, with no bodies and secrets masked |
| Scroll by screens, or scroll a ref into view |
| Wait for text to appear or go away, for the URL to change, or a fixed time |
| JPEG of the active tab; |
| Accept or dismiss the next |
| List, open, switch, or close tabs of this pod only |
| Console messages and uncaught errors from this pod's tabs |
| Give this pod's tabs a fake answer to matching requests |
| Run a JavaScript expression in the active tab |
| Active tab's cookies and web storage; cookie values are never shown ( |
| 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 |
|
| Station debugging port (localhost only) |
|
| Station profile directory |
| auto-detected | Browser executable |
|
| Fixed pod label |
| unset | Set to |
|
|
|
| unset | Set to |
| all groups | Comma-separated tool groups to add to |
|
| Pod window size |
|
| Directory for saved recipes |
| any site | Comma-separated sites pods may open, subdomains included |
| 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.1only. 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_DOMAINSstops 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.
uploadonly takes files from the directory the agent runs in, plusSPECILLUM_UPLOAD_DIRS, and follows links before checking. Everything in those directories can be sent to a website.Saved files stay near the agent.
pdfandharonly 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.storageis 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 thatevaluatecan still read cookies a page can read.Data tools are read-only and redacted.
network,responseandpage_dataonly 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
NOTICEfile 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 toolsclickC
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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Let AI agents use any website you're logged in to. Sessions stay encrypted on your machine.
Let AI agents use your real, signed-in Chrome: tabs, clicks, forms, screenshots and video.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Let your AI agent operate any website through a real, logged-in browser session.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceLets 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.145MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to securely control a user's existing signed-in Chrome browser through isolated tab groups, with strict per-session ownership and no cookie or token exposure.6 npmISC
- AlicenseNot gradedqualityCmaintenanceConnects 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.2Apache 2.0
- AlicenseNot gradedqualityAmaintenanceLets 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 npmISC