argus— mcp server

<p align="center"> <img src="src/assets/argus_banner.png" alt="Argus" width="1000" /> </p>

<p align="center"> Chrome DevTools Protocol MCP server — give AI agents eyes into a live browser. </p>

<p align="center"> <img src="https://img.shields.io/badge/MCP-compatible-blue?style=flat-square" alt="MCP compatible" /> <img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square" alt="Node ≥ 18" /> <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="MIT" /> </p>

Argus connects directly to Chrome via the Chrome DevTools Protocol and exposes browser debugging as MCP tools - no Puppeteer, no Playwright, no browser abstraction layer. Spawn Chrome, attach to tabs, record console output, intercept network requests, inject mocks, and capture screenshots, all from your MCP client.

The name comes from Argus Panoptes - the 100-eyed giant of Greek mythology who could watch everything at once and never fully slept. That's the goal: total visibility into what the browser is doing.

Motivation

Argus came about as part of an ongoing exploration into leveraging agents to reproduce reported issues as well as "manually" debug/record them on the fly. As a result you can expect to see bugs in Argus itself as well as plenty room for improvement and growth over time.

Features

• Console recording — capture console.log/warn/error and unhandled exceptions with stack traces
• Screenshot capture — viewport, full-page, or clipped region, returned as base64 PNG/JPEG
• Network recording — record every request and response including body, headers, timing, and errors
• Network mocking — intercept requests by glob pattern and return custom responses, zero page reload required
• Multi-tab — attach to any number of tabs simultaneously, each with independent recording state
• No dependencies — direct WebSocket connection to Chrome's debug port, no browser driver needed
• Injectable overlay — floating status widget injected into every inspected page showing live counts

Installation

From npm (recommended)

# Install globally
npm install -g @jmsa/argus-mcp
argus-mcp

# Or run without installing
npx @jmsa/argus-mcp

From source

git clone https://github.com/Jmsa/argus
cd argus
npm install
npm run dev

Chrome Canary opens automatically on startup with the Argus welcome page. Connect your MCP client to the stdio transport and start using the tools.

Requirements

• Node ≥ 18
• Google Chrome or Chrome Canary (macOS, Linux, or Windows)

MCP Client Configuration

Claude Code — run this once:

# npm package (recommended)
claude mcp add --transport stdio argus -- argus-mcp

# from source
claude mcp add --transport stdio argus -- npm run dev

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "argus": {
      "type": "stdio",
      "command": "argus-mcp"
    }
  }
}

If running from source instead, use "command": "npm" with "args": ["run", "dev"] and set "cwd" to the project root.

Auto-Launch Behavior

By default, Argus does not automatically launch Chrome when a Claude session starts. Use the browser_launch tool to start Chrome when you need it.

First-run experience

The first time Claude starts with Argus installed, Chrome opens once automatically so you can verify everything is working. A message on the welcome page explains what's happening. After that first session, auto-launch is off unless you enable it.

The auto-launch toggle

The welcome page always shows a Yes / No toggle for auto-launch:

• No (default) — Chrome does not open on Claude start; call browser_launch manually
• Yes — Chrome and the welcome page open automatically at the start of every Claude session

The toggle takes effect immediately and persists across sessions. Your preference is stored in ~/.argus/config.json and can also be edited manually:

{ "autoLaunch": true }

CI / scripted environments

Set ARGUS_NO_LAUNCH=1 to force-skip Chrome launch regardless of the config file. This is useful in CI pipelines or automated environments where a display isn't available.

Tools

Argus exposes 32 tools across eight groups.

Browser

Tabs

Console

Network Recording

Network Mocks

Page

DOM

Banner

Skills

Skills are Claude Code workflows that invoke Argus tools automatically. Install the plugin to get them as slash commands:

/plugin install Jmsa/argus

Documentation

• Architecture — project structure and how the pieces connect
• Configuration — Chrome path, port, headless mode, and custom flags
• Network Mocking — glob patterns, mock priority, and request flow

How It Works

MCP Client (Claude, Inspector, etc.)
        │  stdio
        ▼
  Argus MCP Server
        │  CDP over WebSocket
        ▼
  Chrome / Chrome Canary
        │  per-tab CDPSession
        ▼
  domains: console · screenshot · network · ui

Chrome is spawned as a child process. Argus listens to its stderr for the DevTools listening on ws://... line to get the exact WebSocket URL, then connects. Each tab gets its own CDPSession (multiplexed over a single WebSocket connection) with independent domain state.

Development

npm run dev       # start with tsx (no build step)
npm run build     # compile to dist/
npm run typecheck # type-check without emitting

Chrome profile data is stored at ~/.argus/chrome-profile so Chrome doesn't reinitialise on every restart.

Contributing

Contributions are welcome. Argus is an active exploration project, so there's plenty of room to improve.

Before opening a PR:

1. Fork the repo and create a branch from main
2. Run npm run typecheck — PRs must pass type checking
3. Test your changes against a live browser session
4. Keep commits focused; one logical change per PR

Good areas to contribute:

• New CDP domain wrappers (e.g. Performance, Accessibility)
• Additional skills / slash commands
• Bug reports with reproduction steps
• Documentation improvements

Open an issue first for large changes so we can align on approach before you invest time in implementation.

License

MIT