Content
# Browser MCP Toolkit
A portable, dual-server MCP setup for browser research and interactive automation. `browse-mcp` handles search, page reading, and content extraction; Playwright MCP controls a real Chrome window for clicking, forms, and user-assisted sign-in.
The repository contains only reusable configuration and helper scripts. Browser profiles, cookies, session data, downloads, screenshots, logs, and local environment files are excluded from Git.
## What is included
| Need | Server | What it does |
| --- | --- | --- |
| Search, read pages, extract links and text | `browse-mcp` | Research-oriented browser access |
| Click, type, submit forms, use a signed-in site | Playwright MCP | Controls a headed Chrome instance |
| MFA, CAPTCHA, or an interactive login | Playwright MCP | Lets you finish the sensitive step manually in Chrome |
## Quick start
Requirements: Node.js 18 or newer and an MCP-capable client.
```bash
git clone https://github.com/parigihelori352-cyber/browse.git browser-mcp-toolkit
cd browser-mcp-toolkit
npm install
npm run setup
npm run check
npm run mcp:config
```
Copy the JSON printed by `npm run mcp:config` into your MCP client's configuration. It discovers the project location itself, so it works no matter where the project was cloned. On Windows, `scripts\show-mcp-config.cmd` provides the same output.
`npm run mcp:config` is the recommended path: do not hand-write relative paths and do not use a fixed path copied from somebody else's machine.
## Generated MCP configuration
The helper prints a complete configuration equivalent to the following template. Replace `/absolute/path/to/browser-mcp-toolkit` only if you choose to configure it manually.
```json
{
"mcpServers": {
"browse": {
"command": "node",
"args": ["node_modules/browse-mcp/dist/index.js"],
"cwd": "/absolute/path/to/browser-mcp-toolkit",
"env": { "BROWSE_MCP_EPHEMERAL": "1" }
},
"playwright": {
"command": "node",
"args": [
"node_modules/@playwright/mcp/cli.js",
"--browser=chrome",
"--user-data-dir=/absolute/path/to/browser-mcp-toolkit/profiles/chrome-profile",
"--timeout-action=15000",
"--timeout-navigation=30000",
"--save-session"
],
"cwd": "/absolute/path/to/browser-mcp-toolkit"
}
}
}
```
`browse-mcp` uses standard input/output (stdio), not an HTTP server. There is intentionally no Browse MCP URL such as `localhost:3002`.
## Using the toolkit
Your MCP client normally starts the servers from the configuration. The following commands are for local troubleshooting only:
```bash
npm run browse
npm run playwright
```
On the first Playwright run, a Chrome window opens. Complete any login, MFA, or CAPTCHA manually. Its profile is stored locally in `profiles/chrome-profile/`, so later runs can reuse the session. Never commit that directory.
`BROWSE_MCP_EPHEMERAL=1` is included in the generated configuration to minimize `browse-mcp` state saved outside the project. Remove it only if you deliberately need persistent Browse MCP state.
## Versioning and compatibility
Both server packages are deliberately pinned: `browse-mcp` is pinned to `0.8.2` and `@playwright/mcp` to `0.0.77`. This keeps a known configuration reproducible. Upgrade them intentionally, run `npm install`, run `npm run check`, and verify the generated MCP configuration before publishing an update.
## Security
Read [SECURITY.md](SECURITY.md) before publishing or sharing a working copy. In particular, inspect `git status --ignored` and make sure no profile or session data is staged.
## Project structure
```text
config/ Reference arguments for each MCP server
scripts/show-mcp-config.mjs Cross-platform configuration generator
scripts/check.mjs Local dependency and setup verification
profiles/ Created locally; ignored by Git
```
## License
MIT. See [LICENSE](LICENSE).
