Want Claude Code to inspect your local website, fill a form, and show you the
result? This walkthrough connects it to Bruster, an open-source Rust browser
controller with a built-in Model Context Protocol (MCP) server.
The workflow is small enough to reproduce: open a local fixture, inspect its
controls, enter two values, select an option, check the submitted state, and
return a screenshot.
Bruster uses the platform's native webview. Its server needs no Node.js runtime.
The AI client and browser runtime have their own requirements.
What you need
- Claude Code installed and signed in.
- macOS or Linux for the shell commands below.
- Git and Python 3 to download and serve the example. Python is only the local HTTP server in this walkthrough; Bruster itself does not require it.
Windows is also supported through WebView2. Use the Windows archive and client
configuration in the platform setup guide.
1. Install Bruster
On macOS or Linux:
curl -fsSL https://raw.githubusercontent.com/aliilyas/bruster/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
command -v bruster
On Ubuntu or Debian, also install the native browser runtime:
sudo apt install libwebkit2gtk-4.1-0
On a Linux machine without a desktop display:
sudo apt install xvfb xauth
Hidden mode still needs a rendering display. When DISPLAY is unset, Bruster
tries to start Xvfb automatically.
2. Serve the example website
In one terminal:
git clone https://github.com/aliilyas/bruster.git
cd bruster
python3 -m http.server 8765 --bind 127.0.0.1 --directory examples/launch-demo
Leave this terminal running. Open http://127.0.0.1:8765 to check that the
Browser smoke test form loads. The form updates a JSON preview and displays a
local receipt when submitted; it does not send anything to a service.
3. Register the MCP server with Claude Code
In a second terminal, enter your cloned bruster directory. Run:
claude mcp add --transport stdio bruster -- "$HOME/.local/bin/bruster" --mcp --quiet
claude mcp get bruster
claude
The default registration scope is local to this project. Using an absolute
executable path avoids differences between your terminal's PATH and the
environment that starts an MCP server.
Inside Claude Code, run /mcp and check Bruster's connection. The -- separates
Claude's options from the executable and arguments for Bruster.
4. Give Claude an observable task
Paste this prompt into Claude Code:
Use Bruster to open http://127.0.0.1:8765. Inspect the form before interacting
with it. Enter Ada Lovelace as the name and Bruster as the project. Select
Form submission and enable Include screenshots. Read the live JSON preview
and confirm those four values. Click Create smoke test. Read the confirmation
and verify that it names Bruster and Ada Lovelace and says Screenshots: on.
Return a screenshot of the result. Report any failed check.
The useful part is the verification: ask the agent to read the resulting state,
not just report that it clicked a button.
The browser tools support this sequence:
navigate → snapshot → fill_form → text → click → text → screenshot
Claude may choose a different combination of tools. The expected form state is:
{
"name": "Ada Lovelace",
"project": "Bruster",
"workflow": "forms",
"screenshots": true
}
The receipt heading should be Smoke test created for Bruster. Its details
include Ada Lovelace, Form submission, and Screenshots: on.
This reference image comes from the repository's scripted MCP demo on
WebKitGTK. It shows an actual browser capture; it is not a Claude conversation
recording. The demo transcript and reproduction steps
document the captured build and tool calls.
5. Watch the browser or retain a session
To watch the native window, replace the registration with one that adds
--visible after --mcp:
claude mcp remove bruster
claude mcp add --transport stdio bruster -- "$HOME/.local/bin/bruster" --mcp --quiet --visible
Restart Claude Code after changing the registration. Visible mode needs a
desktop session.
For cookies and storage that persist between runs, add
--profile "$HOME/.local/share/bruster/claude-demo" to the server arguments.
This creates a dedicated Bruster profile; it does not attach to your everyday
browser's existing login session.
Troubleshooting
| Symptom | Check |
|---|---|
| Claude cannot start Bruster | Confirm command -v bruster; use its absolute path in the registration. |
| Linux cannot load the browser | Install WebKitGTK 4.1; on a display-less machine, install both Xvfb and xauth. |
| The local page cannot be reached | Keep the Python server running. The MCP process must be able to reach the same machine's loopback address. |
| The connection fails without details | Remove --quiet temporarily so native runtime errors appear on stderr. |
| The form does not accept an interaction | Bruster uses synthetic DOM events. Check whether the application requires trusted browser input or a cross-origin iframe. |
Where this fits
Bruster is useful for native-webview workflows and focused checks driven by an
agent. Its engines are WKWebView on macOS, WebKitGTK on Linux, and WebView2 on
Windows; WebView2 is Chromium-based. Cross-origin iframe interaction and
OS-level controls are outside its supported surface.
For a selectable multi-engine browser workflow, evaluate Playwright MCP as
well. For a full regression suite, compare test-runner requirements separately
from the MCP interface.
Try the same flow on one form in your application. Start with its visible
result and work backward to the actions needed to produce it.
- MCP setup, client configurations, and troubleshooting
- Bruster source and releases
- Browser-tool comparison
Project-maintainer tutorial, prepared with AI assistance. The form workflow is
reproducible with the included scripted MCP client.
Top comments (0)