How do I use cssprobe-cli?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@cssprobe-cli inspect .sidebar on https://example.com and list overflow issues" 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.

cssprobe-cli

by mack-peng

Overview Schema Source Related Servers Discussions Admin

TypeScript

Local

cssprobe-cli

Runtime CSS probe — inspect layout, scroll, colors, backgrounds, fonts and more in a live browser. Built for both humans and AI agents.

License: MIT Node.js npm version npm downloads GitHub stars

Static + runtime CSS diagnosis for AI agents — pair with cssgraph (the CSS knowledge graph) for the full picture.

Why cssprobe-cli?

When an AI agent needs to debug CSS — why is this element overflowing, what's the actual rendered layout, is this container scrollable — it can't see the browser. It guesses from static code, missing runtime-only issues like overflow, scroll chains, and containing block hijacks.

cssprobe-cli gives the agent eyes. It opens a real browser, collects computed styles and metrics via injected JavaScript, analyzes them with a confidence model, and returns structured findings — all in one command. The agent asks a question about any selector and gets back the DOM tree, ASCII layout diagram, overflow warnings, and scroll diagnosis without leaving the terminal.

Related MCP server: mcp-browser-lens

Installation

For Humans

Copy and paste this prompt to your LLM agent (Claude Code, Cursor, Codex, etc.):

Install and configure cssprobe-cli by following the instructions here:
https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md

Or read the Installation Guide, but seriously, let an agent do it. Humans fat-finger configs.

For LLM Agents

Fetch the installation guide and follow it:

curl -s https://raw.githubusercontent.com/mack-peng/cssprobe-cli/main/docs/guide/installation.md

Or install directly:

npm install -g cssprobe-cli
cssprobe-cli skill-install

How It Works

┌───────────────────────────────────────────────────────────┐
│                      AI Agent                              │
│                                                           │
│  "Is .sidebar overflowing?"                               │
│      calls: cssprobe-cli inspect .sidebar                 │
│                             │                             │
└─────────────────────────────┬─────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────┐
│                  cssprobe-cli daemon                       │
│                                                           │
│  collector (IIFE) → analyzer (pure) → renderer (md/json)  │
│                             │                             │
│                             ▼                             │
│               Playwright browser (Chromium)                │
│     getBoundingClientRect · getComputedStyle · DOM walk    │
└───────────────────────────────────────────────────────────┘

Session — open spawns a daemon process managing a browser. Commands connect via Unix socket.
Collector — Injected as IIFE into the page. Walks the DOM, reads computed styles, declared values, and element metrics.
Analyzer — Pure Node.js functions. Classifies findings with confidence levels (DEFINITE / INDEFINITE / UNVERIFIABLE).
Renderer — Outputs Markdown (default) or JSON. Includes ASCII layout diagram, DOM tree, and findings.

Quick Start

1. Inspect a Page

# Open browser (non-blocking, starts daemon session)
cssprobe-cli open https://getbootstrap.com/docs/5.3/examples/checkout

# Inspect with CSS selector
cssprobe-cli inspect .container

# Show ASCII layout diagram
cssprobe-cli layout .container

# Show only issues/warnings
cssprobe-cli findings .container

# Close browser when done
cssprobe-cli close

# Open browser in headed mode
cssprobe-cli open https://mysite.com --headed

# User manually logs in...

# Save session state for future use
cssprobe-cli state-save --name mysite

# Reopen with saved state (no login needed)
cssprobe-cli open https://mysite.com --state state.json --headed

3. JSON Output

cssprobe-cli inspect body --json
cssprobe-cli inspect body --json | jq '.findings[] | {id, confidence, message}'

4. Use as an MCP Server (AI clients)

cssprobe-cli ships an MCP server (stdio), so AI clients call it as a native tool — no shell needed:

cssprobe-cli mcp-install          # auto-detect and configure installed clients
cssprobe-cli mcp-install --target=claude,cursor,codex
cssprobe-cli mcp-install --local  # write project-scoped config

Manual configuration for any MCP client:

{
  "mcpServers": {
    "cssprobe-cli": { "command": "cssprobe-cli", "args": ["mcp"] }
  }
}

Exposes 10 tools: cssprobe_open, cssprobe_inspect, cssprobe_tree, cssprobe_layout, cssprobe_findings, cssprobe_eval, cssprobe_screenshot, cssprobe_inject_css, cssprobe_close, cssprobe_status. Remove with cssprobe-cli mcp-uninstall.

Commands

Session Management

Command	Description
`open [url]`	Open browser in session mode (non-blocking)
`open [url] --headed`	Show browser window
`open [url] --state <file>`	Open with saved cookies + localStorage
`open [url] --viewport 1280x720`	Custom viewport size
`close`	Close browser session
`close --all`	Close all sessions across all workspaces
`status`	Show session status

CSS Inspection

Command	Description
`inspect <selector>`	Full CSS diagnosis (computed values, declared values, findings)
`inspect <selector> --layout`	Include ASCII layout diagram
`inspect <selector> --brief`	Compact: tree sketch + warnings/errors only
`inspect <selector> --json`	Structured JSON output
`tree <selector>`	DOM tree structure
`layout <selector>`	ASCII layout diagram
`findings <selector>`	Only issues/warnings/errors

CSS Injection

Command	Description
`inject-css <css>`	Inject CSS into current page

Browser

Command	Description
`resize <width> <height>`	Resize browser viewport
`eval <expression>`	Evaluate JavaScript (browser context)
`playwright <call>`	Execute Playwright API (Node.js context)
`screenshot`	Take screenshot (saves to ~/.cssprobe-cli/screenshots/, --out to override)

State

Command	Description
`state-import <file>`	Import cookies from Netscape format
`state-save`	Save current browser session state (cookies + localStorage)

Configuration

Command	Description
`config-show`	Show current config
`config-set <key> <value>`	Set config value
`config-list`	List all profiles
`config-use <name>`	Switch active profile
`config-new <name>`	Create new profile
`config-path`	Show config file path

Confidence Model

Every finding carries a confidence level:

Level	Meaning
DEFINITE	Based on computed values (facts from getComputedStyle) or accessible declared values
INDEFINITE	Declared value uses `%` — resolves at runtime
UNVERIFIABLE	Declared value missing or from blocked cross-origin stylesheet

The report header shows: confidence: DEFINITE 8 | INDEFINITE 0 | UNVERIFIABLE 1

Complementary Tool: cssgraph

cssprobe-cli is a runtime CSS probe — it opens a real browser and reads what is actually rendered. For static questions about the source code — where is .btn-primary defined, what cascades over it, which components reference it, what would change if I edited it — use cssgraph, a local SQLite knowledge graph of every className, property, variable, and at-rule in your stylesheets. The two tools complement each other:

	cssgraph (static)	cssprobe-cli (runtime)
Analyzes	source code (CSS/SCSS/Less + JSX/TSX + templates)	live browser (computed styles + DOM)
Answers	where a class is defined, cascade, impact, unused CSS	actual rendered layout, overflow, scroll, height chains
When	before/without a browser	after static analysis, to verify at runtime
Usage	`cssgraph init` + `explore`/`rule`/`impact`	`open` + `inspect`/`layout`/`findings`

Recommended workflow for a style problem — go static first, then verify at runtime:

# 1. Static: find the definitions, cascade, and blast radius (cssgraph)
cssgraph explore .btn-primary
cssgraph cascade .btn-primary

# 2. Runtime: confirm what actually renders (cssprobe-cli)
cssprobe-cli open https://example.com
cssprobe-cli inspect .btn-primary
cssprobe-cli findings .btn-primary

Install: npm install -g cssgraph (requires Node.js >= 22.5.0). It exposes 12 MCP tools (cssgraph_explore, cssgraph_rule, cssgraph_impact, …) plus CLI commands. See npm / GitHub.

Configuration

# Set values
cssprobe-cli config-set browser chromium
cssprobe-cli config-set depth 8
cssprobe-cli config-set viewport 375x812

# Profile management
cssprobe-cli config-new staging
cssprobe-cli -p staging config-set browser firefox
cssprobe-cli config-use staging

Priority: CLI flags > Environment variables > Config file

--browser       CSSPROBE_BROWSER
--depth         CSSPROBE_DEPTH
--headed        CSSPROBE_HEADED
--viewport      CSSPROBE_VIEWPORT
-p, --profile   CSSPROBE_PROFILE

Config file: ~/.cssprobe-clirc

Supported Platforms

Platform	Architectures
macOS	x64, arm64
Linux	x64, arm64
Windows	x64, arm64

Development

npm install
npm run build       # tsc + esbuild collector + daemon entry + generate help.json
npm test            # Run unit tests (58 tests)
npx tsc --noEmit    # Type check only

If cssprobe-cli is useful

A ⭐ star helps other developers discover it — and tells us to keep shipping.

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

sncro A
io.github.scottconfusedgorilla
Live browser debugging for AI assistants — DOM, console, network via MCP.
Browser Automation Developer Tools Monitoring
2
render-mcp A
io.github.RodRomer
Hosted browser for AI agents: screenshots, post-JS DOM, console, WCAG. No install, no API key.
Browser Automation Testing & QA Tools
61
TabfleetOAuth
com.tabfleet
Launch, inspect, control, and share isolated cloud browsers for your agents.
Agent Orchestration Browser Automation
1
Web Validator by DigestSEO A
io.github.AKzar1el
Validate HTML/CSS, audit SEO and JSON-LD, check links, and capture responsive screenshots.
Marketing Testing & QA Tools Browser Automation
817

Related MCP Servers

MCP Browser Debugger
Browser Automation Web Scraping Developer Tools
EmmanuelBarbosaMonteiro
F
license
A
quality
D
maintenance
Enables comprehensive web frontend debugging and analysis through DOM inspection, JavaScript execution, network monitoring, console log capture, and automated browser interactions. Supports complete web development workflows including testing, data extraction, and performance analysis.
Updated a year ago (2025-10-10 15:31 UTC)
15
-
mcp-browser-lens
Browser Automation Developer Tools Testing & QA Tools
nano-step
A
license
Not graded
quality
D
maintenance
Provides AI agents with deep visibility into a running web page's UI by capturing DOM, styles, and screenshots through a lightweight bookmarklet. It facilitates design-to-code comparisons, accessibility audits, and automated CSS debugging directly within an IDE.
Updated 4 months ago (2026-05-30 06:43 UTC)
34 npm
3
MIT
sargel
Developer Tools Testing & QA Tools Browser Automation
ofriw
A
license
A
quality
D
maintenance
Lets AI agents visually inspect web elements, test CSS edits in real-time, and iterate until pixel-perfect, functioning like browser DevTools for debugging UI issues.
Updated a year ago (2025-09-15 06:39 UTC)
1
6 npm
1
MIT
bettercss
Developer Tools Testing & QA Tools
ikraamg
A
license
Not graded
quality
A
maintenance
Enables CSS layout verification and debugging by extracting deterministic, diffable rendered layout from a browser, allowing agents to inspect, explain, and diff CSS changes.
Updated 12 days ago (2026-09-04 17:41 UTC)
46 npm
2
MIT

cssprobe-cli

Why cssprobe-cli?

Installation

For Humans

For LLM Agents

How It Works

Quick Start

1. Inspect a Page

2. Login-Protected Pages

3. JSON Output

4. Use as an MCP Server (AI clients)

Commands

Session Management

CSS Inspection

CSS Injection

Browser

State

Configuration

Confidence Model

Complementary Tool: cssgraph

Configuration

Supported Platforms

Development

If cssprobe-cli is useful

License

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MCP Browser Debugger

mcp-browser-lens

sargel

bettercss