Content
<p align="center">
<img src=".github/assets/glance-logo.png" alt="Glance" width="80" />
</p>
<h1 align="center">Glance</h1>
<p align="center">
<strong>AI-powered browser automation for Claude Code</strong><br/>
<em>by <a href="https://debugbase.io">DebugBase</a></em>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/glance-mcp"><img src="https://img.shields.io/npm/v/glance-mcp?color=blue&label=npm" alt="npm" /></a>
<a href="https://github.com/DebugBase/glance/blob/main/LICENSE"><img src="https://img.shields.io/github/license/DebugBase/glance" alt="License" /></a>
<a href="https://github.com/DebugBase/glance/stargazers"><img src="https://img.shields.io/github/stars/DebugBase/glance?style=social" alt="Stars" /></a>
<a href="https://discord.gg/RyGk6HP7Uy"><img src="https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white" alt="Discord" /></a>
</p>
<p align="center">
Navigate, click, screenshot, test — all from your terminal.
</p>
---
## What is Glance?
Glance is an [MCP server](https://modelcontextprotocol.io) that gives Claude Code a real browser. Instead of guessing what your web app looks like, Claude can actually **see** it, **interact** with it, and **test** it.
```
You: "Test the login flow on localhost:3000"
Claude: *opens browser* *navigates* *fills form* *clicks submit*
*takes screenshot* *verifies redirect* *checks for errors*
"Login flow works. Found 1 console warning about..."
```
## Features
- **30 MCP tools** for complete browser control
- **Inline screenshots** — Claude sees what the browser sees
- **Accessibility snapshots** — full page structure as text
- **Test scenario runner** — define multi-step tests in JSON
- **12 assertion types** — exists, textContains, urlEquals, and more
- **Session recording** — record and replay browser sessions
- **Visual regression** — pixel-level screenshot comparison
- **Network & console monitoring** — catch errors and failed requests
- **Security controls** — URL allowlist/denylist, rate limiting, JS execution policies
- **Headed mode** — watch the browser in real-time
## Quick Start
### 1. Install
```bash
npm install -g glance-mcp
```
Or add directly to Claude Code:
```bash
claude mcp add glance -- npx glance-mcp
```
### 2. Configure
Add to your `.mcp.json`:
```json
{
"mcpServers": {
"glance": {
"command": "npx",
"args": ["glance-mcp"],
"env": {
"BROWSER_HEADLESS": "false"
}
}
}
}
```
### 3. Use
Just ask Claude to interact with your web app:
```
"Open localhost:3000 and take a screenshot"
"Test the signup flow with invalid email"
"Check if the pricing page has all three tiers"
"Run a visual regression test on the dashboard"
```
## Tools Reference
### Browser Control (19 tools)
| Tool | Description |
|------|-------------|
| `browser_navigate` | Navigate to a URL |
| `browser_click` | Click an element (CSS selector or text) |
| `browser_type` | Type into an input field |
| `browser_hover` | Hover over an element |
| `browser_drag` | Drag and drop between elements |
| `browser_select_option` | Select from a dropdown |
| `browser_press_key` | Press a keyboard key |
| `browser_scroll` | Scroll the page or to an element |
| `browser_screenshot` | Capture a screenshot (returned inline to Claude) |
| `browser_snapshot` | Get the accessibility tree as text |
| `browser_evaluate` | Execute JavaScript in the page |
| `browser_console_messages` | Read console logs and errors |
| `browser_network_requests` | Monitor network activity |
| `browser_go_back` | Navigate back |
| `browser_go_forward` | Navigate forward |
| `browser_tab_new` | Open a new tab |
| `browser_tab_list` | List all open tabs |
| `browser_tab_select` | Switch to a tab |
| `browser_close` | Close the browser |
### Test Automation (7 tools)
| Tool | Description |
|------|-------------|
| `test_scenario_run` | Run a multi-step test scenario |
| `test_scenario_status` | Check running scenario status |
| `test_assert` | Run a single assertion |
| `test_fill_form` | Auto-fill a form |
| `test_auth_flow` | Test a login/signup flow |
| `test_watch_events` | Watch for DOM/network events |
| `test_stop_watch` | Stop watching events |
### Session & Visual (4 tools)
| Tool | Description |
|------|-------------|
| `session_start` | Start recording a session |
| `session_end` | End and save a session |
| `session_list` | List recorded sessions |
| `visual_baseline` | Save a visual baseline |
| `visual_compare` | Compare against baseline |
## Test Scenarios
Define multi-step test scenarios in JSON:
```json
{
"name": "Login Flow",
"steps": [
{ "name": "Go to login", "action": "navigate", "url": "http://localhost:3000/login" },
{ "name": "Enter email", "action": "type", "selector": "input[type='email']", "value": "user@test.com" },
{ "name": "Enter password", "action": "type", "selector": "input[type='password']", "value": "password123" },
{ "name": "Click submit", "action": "click", "selector": "button[type='submit']" },
{ "name": "Wait for redirect", "action": "sleep", "ms": 2000 },
{ "name": "Verify dashboard", "action": "assert", "type": "urlContains", "expected": "/dashboard" },
{ "name": "Screenshot result", "action": "screenshot", "screenshotName": "post-login" }
]
}
```
### Assertion Types
| Type | Description |
|------|-------------|
| `exists` | Element exists in DOM |
| `notExists` | Element does not exist |
| `textContains` | Element text contains value |
| `textEquals` | Element text equals value |
| `hasAttribute` | Element has attribute with value |
| `hasClass` | Element has CSS class |
| `isVisible` | Element is visible |
| `isEnabled` | Element is enabled |
| `urlContains` | Current URL contains value |
| `urlEquals` | Current URL equals value |
| `countEquals` | Number of matching elements |
| `consoleNoErrors` | No console errors |
## Configuration
All configuration is via environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
| `BROWSER_HEADLESS` | `true` | Run browser in headed mode |
| `BROWSER_SESSIONS_DIR` | `.browser-sessions` | Directory for screenshots and sessions |
| `BROWSER_SECURITY_PROFILE` | `local-dev` | Security profile (`local-dev`, `restricted`, `open`) |
| `BROWSER_VIEWPORT_WIDTH` | `1280` | Browser viewport width |
| `BROWSER_VIEWPORT_HEIGHT` | `720` | Browser viewport height |
| `BROWSER_TIMEOUT` | `30000` | Default timeout in ms |
| `BROWSER_CHANNEL` | — | Browser channel (e.g., `chrome`, `msedge`) |
### Security Profiles
| Profile | URL Access | JS Execution | Rate Limit |
|---------|-----------|--------------|------------|
| `local-dev` | All HTTP/HTTPS | Always | 60/min |
| `restricted` | localhost only | Disabled | 30/min |
| `open` | Everything | Always | 120/min |
## How It Works
```mermaid
graph LR
A["Claude Code<br/>(Agent)"] -- "MCP stdio<br/>tools & results" --> B["Glance<br/>(MCP Server)"]
B -- "Playwright<br/>automation API" --> C["Browser<br/>(Chromium)"]
C -- "screenshots<br/>DOM snapshots" --> B
B -- "inline images<br/>a11y trees" --> A
```
1. Claude Code connects to Glance via MCP (stdio transport)
2. Claude calls tools like `browser_navigate`, `browser_screenshot`
3. Glance translates these into Playwright commands
4. Screenshots are returned as base64 images — Claude literally sees the page
5. Accessibility snapshots give Claude the full DOM structure as text
## Real-World Usage
Glance has been battle-tested on production apps:
- **DebugBase** (debugbase.io) — 12 scenarios, 104 test steps, 97% pass rate
- **GitScribe AI** — 16 scenarios, 196 test steps, 96% pass rate
## Requirements
- Node.js 18+
- Playwright-compatible browser (auto-installed)
## Development
```bash
git clone https://github.com/DebugBase/glance.git
cd glance
npm install
npx playwright install chromium
npm run build
npm start
```
## Claude Code Integration
### Agent: `e2e-tester`
Glance ships with a Claude Code agent definition for comprehensive browser testing. The agent knows all 30 tools and follows a structured test workflow: navigate, screenshot, assert, report.
```
You: "Test the entire login flow on localhost:3000"
Agent: Opens browser → navigates → fills forms → clicks → screenshots → asserts → reports
```
### Skill: `/glance-test`
Quick E2E test runner. Just provide a URL:
```
/glance-test https://myapp.com
```
The skill will:
1. Navigate to the URL
2. Screenshot and snapshot the page
3. Discover all navigation links
4. Test each page with assertions
5. Check console for JS errors
6. Generate a pass/fail report
## Contributing
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
[MIT](LICENSE) — built by [DebugBase](https://debugbase.io)
