@mindstone/mcp-server-browser-automation 0.1.7 → 0.1.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -12
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,8 +1,87 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mindstone/mcp-server-browser-automation
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
|
|
4
|
+
[](./LICENSE)
|
|
4
5
|
|
|
5
|
-
|
|
6
|
+
Browser control you can watch: open pages, sign in, click around, fill forms, take screenshots, and keep a reusable browser session.
|
|
7
|
+
|
|
8
|
+
*Best for practical web tasks where the user needs to see, approve, or reuse browser state instead of running a full browser-testing stack.*
|
|
9
|
+
|
|
10
|
+
## Status
|
|
11
|
+
|
|
12
|
+
- **Version:** [0.1.7](./CHANGELOG.md) · [npm](https://www.npmjs.com/package/@mindstone/mcp-server-browser-automation)
|
|
13
|
+
- **Auth:** None ([`server.json`](./server.json))
|
|
14
|
+
- **Tools:** [18](./src/tools/) (navigation, observation, interaction, sessions)
|
|
15
|
+
- **Surface:** browser-automation
|
|
16
|
+
- **Machine-readable:** [`STATUS.json`](./STATUS.json)
|
|
17
|
+
|
|
18
|
+
## Why this exists
|
|
19
|
+
|
|
20
|
+
Microsoft's Playwright MCP is a strong choice for broad browser automation and testing. This connector is deliberately smaller and more visible.
|
|
21
|
+
|
|
22
|
+
Use it when an assistant needs to work through ordinary websites in a way a person can follow: open a real browser, let the user complete a login, click through admin screens, fill forms, take screenshots, and come back to the same session later. The point is trust and day-to-day usefulness, not exposing every browser-testing capability.
|
|
23
|
+
|
|
24
|
+
## Example interaction
|
|
25
|
+
|
|
26
|
+
> "Open https://example.com, tell me the page title, and take a screenshot."
|
|
27
|
+
|
|
28
|
+
Tools the host calls:
|
|
29
|
+
1. `browser_navigate` — opens the URL in the configured browser session.
|
|
30
|
+
2. `browser_get_page_info` — returns the current URL and page title.
|
|
31
|
+
3. `browser_screenshot` — captures a PNG screenshot.
|
|
32
|
+
|
|
33
|
+
Response (trimmed):
|
|
34
|
+
|
|
35
|
+
```json
|
|
36
|
+
{
|
|
37
|
+
"ok": true,
|
|
38
|
+
"url": "https://example.com/",
|
|
39
|
+
"title": "Example Domain"
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## Requirements
|
|
44
|
+
|
|
45
|
+
- Node.js 20+
|
|
46
|
+
- npm
|
|
47
|
+
- The `agent-browser` CLI on `PATH`, or `npx` available so the server can install it automatically.
|
|
48
|
+
|
|
49
|
+
<!-- BEGIN INSTALL_LINKS: do not edit by hand; regenerated by scripts/gen-install-links.mjs -->
|
|
50
|
+
## One-click install
|
|
51
|
+
|
|
52
|
+
[](cursor://anysphere.cursor-deeplink/mcp/install?name=Browser%20Automation&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBtaW5kc3RvbmUvbWNwLXNlcnZlci1icm93c2VyLWF1dG9tYXRpb24iXSwiZW52Ijp7IkFHRU5UX0JST1dTRVJfU0VTU0lPTl9OQU1FIjoibWNwIiwiQUdFTlRfQlJPV1NFUl9TSE9XX1dJTkRPVyI6InRydWUifX0)
|
|
53
|
+
[](vscode:mcp/install?%7B%22name%22%3A%22Browser%20Automation%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-browser-automation%22%5D%2C%22env%22%3A%7B%22AGENT_BROWSER_SESSION_NAME%22%3A%22mcp%22%2C%22AGENT_BROWSER_SHOW_WINDOW%22%3A%22true%22%7D%7D)
|
|
54
|
+
[](vscode-insiders:mcp/install?%7B%22name%22%3A%22Browser%20Automation%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40mindstone%2Fmcp-server-browser-automation%22%5D%2C%22env%22%3A%7B%22AGENT_BROWSER_SESSION_NAME%22%3A%22mcp%22%2C%22AGENT_BROWSER_SHOW_WINDOW%22%3A%22true%22%7D%7D)
|
|
55
|
+
|
|
56
|
+
After clicking the button, your host will prompt you to fill: `AGENT_BROWSER_SESSION_NAME`, `AGENT_BROWSER_SHOW_WINDOW`.
|
|
57
|
+
|
|
58
|
+
<details>
|
|
59
|
+
<summary>Manual config for Claude Desktop / Claude Code / Goose / Continue.dev (Browser Automation)</summary>
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"mcpServers": {
|
|
64
|
+
"Browser Automation": {
|
|
65
|
+
"command": "npx",
|
|
66
|
+
"args": [
|
|
67
|
+
"-y",
|
|
68
|
+
"@mindstone/mcp-server-browser-automation"
|
|
69
|
+
],
|
|
70
|
+
"env": {
|
|
71
|
+
"AGENT_BROWSER_SESSION_NAME": "mcp",
|
|
72
|
+
"AGENT_BROWSER_SHOW_WINDOW": "true"
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
</details>
|
|
80
|
+
<!-- END INSTALL_LINKS -->
|
|
81
|
+
|
|
82
|
+
## Quick Start
|
|
83
|
+
|
|
84
|
+
### npx
|
|
6
85
|
|
|
7
86
|
```bash
|
|
8
87
|
npx -y @mindstone/mcp-server-browser-automation
|
|
@@ -15,14 +94,12 @@ npm install -g @mindstone/mcp-server-browser-automation
|
|
|
15
94
|
mcp-server-browser-automation
|
|
16
95
|
```
|
|
17
96
|
|
|
18
|
-
## Requirements
|
|
19
|
-
|
|
20
97
|
This server requires the `agent-browser` CLI binary to control the browser.
|
|
21
98
|
|
|
22
99
|
### Binary Resolution
|
|
23
100
|
|
|
24
101
|
1. **PATH lookup** (preferred): If `agent-browser` is on your PATH, it is used directly.
|
|
25
|
-
2. **npx fallback**: If the binary is not found, the server automatically falls back to `npx -y agent-browser@0.
|
|
102
|
+
2. **npx fallback**: If the binary is not found, the server automatically falls back to `npx -y agent-browser@0.26.0`.
|
|
26
103
|
|
|
27
104
|
### Installing agent-browser
|
|
28
105
|
|
|
@@ -39,7 +116,8 @@ No API keys or credentials are required. The server communicates with the browse
|
|
|
39
116
|
| Variable | Required | Description |
|
|
40
117
|
|---|---|---|
|
|
41
118
|
| `AGENT_BROWSER_SESSION_NAME` | No | Session name for browser persistence (default: `mcp`) |
|
|
42
|
-
| `
|
|
119
|
+
| `AGENT_BROWSER_SHOW_WINDOW` | No | Set to `false` to run without a visible browser window. Default is visible (`true`). |
|
|
120
|
+
| `BROWSER_AUTOMATION_ALLOW_EVAL` | No | Set to `1` to register the `browser_evaluate` tool. Off by default. See [Security notes](#security-notes). |
|
|
43
121
|
|
|
44
122
|
### MCP Host Configuration
|
|
45
123
|
|
|
@@ -75,7 +153,7 @@ No API keys or credentials are required. The server communicates with the browse
|
|
|
75
153
|
- **browser_scroll** — Scroll the page in a direction
|
|
76
154
|
- **browser_select** — Select an option from a dropdown
|
|
77
155
|
- **browser_hover** — Hover over an element
|
|
78
|
-
- **browser_evaluate** — Execute JavaScript in the page context (gated; see [Security
|
|
156
|
+
- **browser_evaluate** — Execute JavaScript in the page context (gated; see [Security notes](#security-notes))
|
|
79
157
|
|
|
80
158
|
### Session Management
|
|
81
159
|
- **browser_tabs** — List open tabs or switch to a tab
|
|
@@ -91,7 +169,7 @@ The typical workflow uses accessibility snapshots for reliable element targeting
|
|
|
91
169
|
3. `browser_click` / `browser_fill` → interact using @ref references
|
|
92
170
|
4. `browser_screenshot` → visual verification
|
|
93
171
|
|
|
94
|
-
## Security
|
|
172
|
+
## Security notes
|
|
95
173
|
|
|
96
174
|
Browser automation has a large attack surface: the agent-browser CLI controls a real headless browser that loads URLs you pass it, runs page-side JavaScript, and persists cookies and session state across runs. Read this section before deploying.
|
|
97
175
|
|
|
@@ -103,7 +181,7 @@ Browser automation has a large attack surface: the agent-browser CLI controls a
|
|
|
103
181
|
BROWSER_AUTOMATION_ALLOW_EVAL=1 mcp-server-browser-automation
|
|
104
182
|
```
|
|
105
183
|
|
|
106
|
-
Without this env var, `browser_evaluate` is **not** in the tools list at all — the LLM cannot even see it. When enabled, the tool is
|
|
184
|
+
Without this env var, `browser_evaluate` is **not** in the tools list at all — the LLM cannot even see it. When enabled, the tool is marked so MCP hosts can require explicit user confirmation before each invocation.
|
|
107
185
|
|
|
108
186
|
### URL scheme deny-list
|
|
109
187
|
|
|
@@ -129,6 +207,6 @@ To override the session name (for example, to keep separate profiles per project
|
|
|
129
207
|
- **Require host confirmation** for `browser_authenticate` and any flow that may navigate to authenticated sites — otherwise prompt injection in fetched content can drive the browser at sites the user is logged into.
|
|
130
208
|
- **Treat returned page content as untrusted** — accessibility snapshots, screenshots, and JavaScript-evaluation outputs come from arbitrary websites and may contain prompt-injection attempts.
|
|
131
209
|
|
|
132
|
-
##
|
|
210
|
+
## Licence
|
|
133
211
|
|
|
134
|
-
FSL-1.1-MIT
|
|
212
|
+
[FSL-1.1-MIT](./LICENSE) — Functional Source License, Version 1.1, with MIT future licence. The software converts to MIT licence on 2030-04-08.
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mindstone/mcp-server-browser-automation",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.8",
|
|
4
4
|
"mcpName": "io.github.mindstone/mcp-server-browser-automation",
|
|
5
|
-
"description": "Browser automation MCP server
|
|
5
|
+
"description": "Browser automation MCP server — visible-by-default browser control via accessibility snapshots, navigation, form filling, screenshots, and tab management. Set AGENT_BROWSER_SHOW_WINDOW=false to run quietly.",
|
|
6
6
|
"license": "FSL-1.1-MIT",
|
|
7
7
|
"type": "module",
|
|
8
8
|
"bin": {
|