Content
# Browser MCP Server 🚀
[English](README_EN.md) | 简体中文
[](LICENSE) [](https://www.python.org/downloads/) [](https://github.com/hihuzhen/browser-mcp/stargazers) [](https://github.com/hihuzhen/browser-mcp/network/members) [](https://github.com/hihuzhen/browser-mcp/pulls)
Browser MCP Server is a WebSocket-based implementation of a browser MCP (Model Context Protocol) server that allows AI assistants to control your browser.
## 🚀 Project Features
- **WebSocket Communication**: Utilizes WebSocket to replace the original communication method, providing more efficient bidirectional communication.
- **Python Backend**: The app server is completely rewritten in Python, utilizing the FastMCP framework.
- **Browser Automation**: Allows AI assistants to perform various browser operations.
- **Local Execution**: Runs entirely locally to ensure user privacy.
- **Multi-Tool Support**: Supports various tools such as screenshots and interactive operations.
## 📁 Project Structure
```
├── packages/ # Project packages
│ ├── app/ # Python implementation of the MCP server
│ │ ├── src/nep_browser_engine/ # Main source directory
│ │ ├── pyproject.toml # Python project configuration
│ │ └── .gitignore # Gitignore file for the Python project
│ └── extension/ # Chrome browser extension
│ ├── common/ # Common code and constants
│ ├── entrypoints/ # Entry points (background and popup)
│ └── inject-scripts/ # Scripts injected into web pages
├── .gitignore # Root directory gitignore file
└── LICENSE # License file
```
### App Section (Python Implementation)
Main components:
- **WebSocket Service**: Implements the WebSocket server responsible for communication with the browser extension.
- **MCP Service**: Implements the MCP protocol, providing various browser control tools.
- **Message Handling**: Handles WebSocket messages and MCP tool calls.
### Extension Section (TypeScript Implementation)
Main components:
- **WebSocket Client**: Responsible for communication with the Python server.
- **Tool Handler**: Handles tool call requests from the server.
- **Inject Scripts**: Executes various operations within web pages.
## 🛠️ Core Features
### Page Interaction
- **Element Click**: Click on page elements using CSS selectors.
- **Form Filling**: Fill out forms or select options.
- **Keyboard Operations**: Simulate keyboard input.
- **Get Page Content**: Extract text and HTML from the page.
- **Get Elements**: Retrieve specific elements from the page.
- **Interactive Element Recognition**: Automatically identify interactive elements on the page.
### Media and Network
- **Screenshot**: Capture the entire page or specific elements.
## 🚀 Quick Start
### Prerequisites
- Python 3.9+ and pip/poetry/uv
- Chrome/Chromium browser
### Installation Steps
#### 1. Install Chrome Extension
```bash
cd extension
pnpm install
pnpm run build
# Or download a specific version from releases
```
Then in Chrome browser:
1. Open `chrome://extensions/`
2. Enable "Developer mode"
3. Click "Load unpacked extension"
#### 2. Run the Service
```json
{
"mcpServers": {
"nep-browser-engine": {
"type": "stdio",
"command": "uvx",
"args": ["nep-browser-engine"]
}
}
}
```
#### 3. Connect Extension and Service
Click the extension icon in the browser to connect to the WebSocket service.
## 📝 Usage Instructions
### Use with MCP Protocol Clients
This service can be used with AI clients that support the MCP protocol, such as Claude, CherryStudio, etc.
## 🛠️ Available Tools List
Here are the main available tools:
### Browser Management
- `get_windows_and_tabs`: Get all open windows and tabs.
- `browser_navigate`: Navigate to a URL or refresh the current tab.
- `browser_close_tabs`: Close specific tabs or windows.
- `browser_go_back_or_forward`: Go back or forward in browser history.
### Page Interaction
- `browser_click_element`: Click on a page element.
- `browser_fill_or_select`: Fill out forms or select options.
- `browser_get_elements`: Get page elements.
- `browser_keyboard`: Simulate keyboard input.
- `browser_get_web_content`: Get web content.
- `browser_screenshot`: Capture a screenshot of the page.
## 🔧 Development Guide
### Python Server Development
1. Ensure all dependencies are installed.
2. You can configure WebSocket port and other parameters by modifying `app/src/nep_browser_engine/config.py`.
3. At runtime, you can specify the transport protocol with the parameter: `python -m nep_browser_engine.app --transport stdio`.
### Chrome Extension Development
1. After modifying the code, run `pnpm run build` to rebuild the extension.
2. The extension will automatically reload (if in developer mode).
3. The default WebSocket connection address is `ws://localhost:18765`.
## 📋 Notes
- This project is still under development and may have some bugs and imperfections.
- Please ensure you understand the functionality and potential risks of all tools before use.
- Do not use this project for any illegal or unauthorized activities.
## 🤝 Contribution
Contributions in the form of issues and PRs to help improve this project are welcome!
## Acknowledgments
This project references [hangwin/mcp-chrome](https://github.com/hangwin/mcp-chrome).
## 📄 License
[MIT License](LICENSE)
