# ghostlight [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/sylin-org/ghostlight  
**GitHub Stars:** 1  
**npm Downloads (last month):** 1465  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/ghostlight

## Description
Drive your real logged-in browser from any MCP client. Governed or wide open, one portable binary.

## Tools
Capabilities this server exposes over MCP:

- **browser_tabs** — List, focus, or close this session's tabs. List gives fresh handles from the live browser; with no tab yet it needs none and names those connected.
- **browser_navigate** — Go to an HTTP(S) URL. Reuses the obvious tab; new_tab true opens a new one.
- **browser_history** — Go back or forward, or reload. A new document invalidates target_ and view_ handles, so collect fresh ones.
- **browser_window** — Set a tab's zoom or resize its browser window. Either invalidates view_ handles, so take a fresh screenshot before coordinate work.
- **browser_read** — Read visible page text, including open shadow roots and frames, or one target. To act, get handles from browser_inspect or browser_find.
- **browser_inspect** — Inspect controls or page structure for fresh target_ handles. Scope document returns the outline as a bounded tree, without handles. Form controls also carry their value and what they accept: options, type, limits, hint and group.
- **browser_find** — Find targets by visible or accessible text and get fresh target_ handles. Fastest when you know the label. Option text finds its dropdown.
- **browser_screenshot** — Capture the viewport, full page, one target, or a magnified region; returns a view_ handle for coordinate calls.
- **browser_click** — Click a target_ handle, a control found by selector, or a point in a view_ screenshot. Needs action; a selector lookup or expect check also needs read. Prefer a target.
- **browser_scroll** — Scroll the page (default down, medium), reveal a target_, or wheel-scroll at a point in a view_ screenshot.
- **browser_hover** — Hover a target_ handle or a point in a view_ screenshot.
- **browser_fill_form** — Fill 1 to 30 fields in one call; needs write even for unsent drafts. Nothing submits unless submit_target names the control. A value a control cannot take is refused before any field changes, with what it accepts. For credentials, set user_authorized_credentials only on the user's explicit instruction.
- **browser_type_text** — Type through real keyboard input. Needs action; a selector lookup or expect check also needs read. Prefer browser_fill_form for plain values. For credentials, set user_authorized_credentials only on the user's explicit instruction.
- **browser_press_key** — Send a named key or literal character, optionally at a target_. Needs action; an expect check also needs read. For Control+A send key a with modifiers Control; strokes sends keys in order.
- **browser_drag** — Drag between two target_ handles or two points in one view_ screenshot.
- **browser_wait** — Wait for one observable page condition. A false condition is a failed result, not an unknown effect.
- **browser_dialog** — Read the open JavaScript dialog with status, then accept, dismiss, or answer it; it blocks its page.
- **browser_upload** — Attach local paths, inline files, or one captured image to a file input, or drop the image at a point in a view_. Needs write; a selector lookup also needs read.
- **browser_execute** — Run JavaScript in the page main world. It may read, mutate, or navigate; prefer a semantic tool. A script that is one expression is awaited, so a promise it evaluates to resolves.
- **browser_flow** — Run 1 to 20 tool calls. tab defaults tab-scoped steps; a step's own tab wins. Later arguments may reference earlier results. Stops at the first failed step by default.
- **browser_record** — Record browser work as a short memory-only GIF. One recording per session; save stops an active capture.
- **browser_diagnose** — Read opt-in console and network observations for a tab. Observation begins with the first call, so reload or reproduce to capture earlier activity. Sensitive request data is never collected.
- **policy_explain** — Explain the authority in force: one line per capability with its deciding layer, the rules behind them, permanent ceilings, and each layer's document. Available under every authority; use it to learn why a call was refused or what is allowed.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "ghostlight": {
    "command": "npx",
    "args": ["-y","ghostlight"]
  }
}
```

## Documentation

## What ghostlight does

The ghostlight MCP server gives an MCP client access to a tab group in an existing Chromium-based browser. It works with Chrome, Edge, Brave, or Chromium 125 and newer, using the browser profile selected by the user. This lets an agent use sessions and sign-ins already present in that browser instead of opening a separate empty browser.

The agent can read pages, navigate, inspect browser state, interact with semantic elements, complete forms, upload files, follow supported child tabs, resolve dialogs, wait for page changes, and investigate failed workflows. The work remains visible in the selected browser window. A desktop tray workbench shows activity and lets the user pause the workspace, take control for a delicate step, or stop it.

The ghostlight MCP server keeps ordinary browser tabs outside the agent-owned set and follows the workspace if its tabs are moved. It also reports what happened, what changed, whether the result is uncertain, and whether repeating the operation is considered safe. Its local record contains identifiers, decisions, and minimized measurements rather than page content, field values, screenshots, selectors, or dialog text.

## How it works

An MCP client sends an intended browser operation to the local Ghostlight service. The service communicates with the browser through the installed extension over local IPC, performs the browser steps, and returns a structured result. The published release describes 23 browser tools and one policy tool covering tabs, navigation, page reads, screenshots, clicks, hovers, form input, uploads, scripts, waits, short flows, dialogs, diagnostics, and workspace switching.

Browser credentials remain in the chosen browser profile. Credential entry requires explicit acknowledgement for the request, and that acknowledgement cannot bypass policy or the user’s Pause or Stop controls. With no policy configured, HTTP and HTTPS browsing is allowed, including localhost, loopback, and link-local destinations; non-HTTP schemes and stale handles remain restricted.

## Setup and configuration

Install the local service and register MCP clients discovered by the installer with:

```sh
npx -y ghostlight install
```

Then install the Ghostlight in Browser extension from the Chrome Web Store and restart an MCP client if it does not reload tools automatically. A first read-only task against `https://example.com/` can verify the connection without clicking, typing, submitting, or changing the page.

Run `npx -y ghostlight doctor` when setup needs diagnosis. It checks the MCP client entry, local service, browser connection, and extension, then identifies the next action. The ghostlight MCP server can also use optional policy layers to grant or restrict `read`, `action`, `write`, and `execute` capabilities by MCP identity and domain. Policies may add sacred domains, dry-run preflight, and structured audit information.

## Tools and capabilities

The ghostlight MCP server supports these capability areas:

- Managing workspaces, owned tabs, navigation, and supported child tabs
- Reading pages, taking screenshots, and referencing page elements
- Clicking, hovering, typing, filling forms, uploading files, and handling dialogs
- Running scripts, waiting for page state, and executing short browser flows
- Collecting page state, console messages, and network requests for diagnostics
- Explaining the authority currently applied through a policy tool

## Limitations and notes

The service operates on the local machine and does not require an account, telemetry, activation service, hosted control plane, or hidden second browser. Network traffic is limited to browsing requested by the agent. Local and managed policy layers can remove authority but cannot add it.

Closing a tab requires both orchestrator authority and the browser’s preserve-tabs setting; that setting is enabled by default. The user can always close a tab manually. Browser messages and animations are passive, while interactive runtime control is handled in the workbench. Non-HTTP URLs and stale element handles are restricted, and uncertain effects are reported instead of being presented as successful.

_Full upstream README: https://allmcps.com/mcp/ghostlight/readme_