Blowback

Blowback MCP Server integrates your frontend development workflow with AI tools, enabling you to run a local FE dev server alongside browser automation, HMR event monitoring, and log capture through the Model Context Protocol. This setup helps you iterate faster by letting AI assist with debugging, state capture, and UI inspection while your app runs locally.

How to use

You use Blowback by running the MCP server alongside your frontend development environment. The server exposes a standard set of browser and development tools that allow AI assistants to monitor HMR events, capture console logs, take screenshots, inspect DOM elements, and control a browser session during development.

To start Blowback with Claude Code, run the following command in your project directory, ensuring your environment variables are set as needed: claude mcp add blowback -s project -e PROJECT_ROOT=/path/to/your/project -- npx -y blowback-context.

How to install

Prerequisites you need on your machine before installing Blowback:

• Node.js (LTS version)
• npm (comes with Node.js)
• Python (if you plan to use Python tooling)
• Playwright (for browser automation)

Step-by-step setup:

• Clone the project directory that provides Blowback MCP support.
• Install dependencies with npm install or your preferred package manager.
• Ensure your environment includes the required tools for your FE development server (e.g., a running Vite project).
• Start Blowback using your chosen MCP command as shown in the configuration examples below.

Additional sections

Configuration notes: Blowback defines a stdio MCP server that runs a local command to launch the context. The example uses npx -y blowback-context with the PROJECT_ROOT environment variable pointing to your frontend project. You can adjust the PROJECT_ROOT to your workspace path as needed.

Environment variables used by Blowback:

• PROJECT_ROOT: Project root path (optional, defaults to the current working directory).
• ENABLE_BASE64: Include base64 encoded images in tool responses (default: false).

Checkpoints, logs, and screenshots are managed by Blowback to help you compare states across snapshots and to review browser activity. Screenshots are stored under the project’s .mcp_screenshot/ directory and metadata is kept in a SQLite database for efficient querying.

Troubleshooting tips: ensure your frontend dev server is reachable from the browser automation environment, verify that the PROJECT_ROOT path exists, and confirm that the CLI/CLI-like tools used by Blowback are installed in your project. If you encounter HMR-related issues, remember that HMR monitoring can start automatically when the browser session is launched.

Available tools

get-hmr-events

Retrieves recent HMR events from the development server to help you understand module updates and errors in real time.

check-hmr-status

Checks the current HMR status to verify whether the frontend server is accepting updates and whether updates are being applied correctly.

start-browser

Starts a browser instance that navigates to the development server and enables automatic HMR monitoring.

capture-screenshot

Captures a screenshot of the current page or a specific element and returns a screenshot ID and resource URI for later retrieval.

get-element-properties

Retrieves properties and state information for a specified DOM element in the page.

get-element-styles

Retrieves computed style information for a specified DOM element.

get-element-dimensions

Retrieves the dimensions and position of a specified element on the page.

monitor-network

Monitors network requests for a specified duration to help diagnose loading issues.

get-element-html

Retrieves the HTML content of a specified element and its descendants.

get-console-logs

Retrieves console logs from the browser session, with optional filtering by level or source.

execute-browser-commands

Safely executes predefined browser commands to interact with the page.

how-to-use

Provides instructions on using specific features of the server and tooling.