About headlessstage
headlessstage is a CLI and stdio MCP server for browser automation through an injected Puppeteer-compatible executor. It supports page interaction, screenshots, and JavaScript evaluation without bundling a browser.
Key features
- 01Navigate to URLs
- 02Click, hover, and interact with forms
- 03Capture page or element screenshots
- 04Evaluate JavaScript in the page
- 05Require an injected browser executor
Use cases
- 01Automate form entry in a browser
- 02Capture screenshots of pages or elements
- 03Run JavaScript against a page during automation
MCP support
Exposes MCP tools for browser navigation, screenshots, clicking, hovering, form interaction, and JavaScript evaluation. A Puppeteer-compatible browser executor must be injected; the package does not bundle a browser.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
7Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | The URL to navigate the browser to |
| launchOptions | object | No | Optional Puppeteer launch options object for the browser instance |
| allowDangerous | boolean | No | Whether to allow dangerous launch options such as disabling the browser sandbox |
Details
From the project READMEheadlessstage
Browser automation through a headless browser page, as a CLI and a stdio MCP server in one bin. Navigate to a URL, click, hover, fill and select form elements, take named screenshots and evaluate JavaScript in the page.
The browser itself sits behind an injectable executor interface
(BrowserExecutor in src/types.ts). This package bundles no
browser and downloads none: with no executor configured, browser
commands fail with a clear "Browser unavailable" error. Deployments
inject a Puppeteer-compatible executor to drive a real browser.
Launch options that weaken browser security (--no-sandbox,
--disable-web-security, --allow-insecure-localhost) are
rejected unless a call explicitly passes allowDangerous: true.
Install
npx -y @reneturcios/headlessstage mcp
CLI
headlessstage mcp # stdio MCP server
headlessstage navigate <url>
headlessstage screenshot <name> [selector]
headlessstage click <selector>
headlessstage fill <selector> <value>
headlessstage evaluate <script>
headlessstage --version
Exit codes: 0 success, 1 browser error, 2 usage error.
MCP tools
| Tool | Purpose |
|---|---|
puppeteer_navigate | Navigate to any URL in the browser |
puppeteer_screenshot | Capture screenshots of the entire page or specific elements |
puppeteer_click | Click elements on the page |
puppeteer_hover | Hover elements on the page |
puppeteer_fill | Fill out input fields |
puppeteer_select | Select an element with a SELECT tag |
puppeteer_evaluate | Execute JavaScript in the browser console |
MCP client config:
{
"mcpServers": {
"headlessstage": {
"command": "npx",
"args": ["-y", "@reneturcios/headlessstage", "mcp"]
}
}
}
Docker
docker run -i ghcr.io/cloudcorprecords/headlessstage # MCP server
docker run --rm ghcr.io/cloudcorprecords/headlessstage --version
Development
npm install
npm run build
npm test
MIT license.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.