Content
# Local Browser MCP Server
A Model Context Protocol (MCP) server that provides browser automation capabilities using Puppeteer, plus AI image generation using Google Gemini 2.0 Flash. This server allows you to control a local Chrome browser instance, take screenshots, perform interactions like clicking and typing, and generate custom images - perfect for testing websites and creating content with Cursor.
## Features
- 🌐 **Browser Navigation**: Navigate to URLs, go back/forward, refresh pages
- 📸 **Screenshots**: Capture full page, viewport, or specific element screenshots
- 🖱️ **Click Actions**: Click on elements using CSS selectors
- ⌨️ **Text Input**: Type text into input fields and forms
- 📜 **Scrolling**: Scroll pages in any direction
- ⏳ **Wait Operations**: Wait for elements to appear
- 📊 **Page Info**: Get current page title, URL, and viewport information
- 🎨 **AI Image Generation**: Generate custom images using Google Gemini 2.0 Flash Preview
## Installation
1. **Clone/Download** this repository to your local machine
2. **Install dependencies**:
```bash
npm install
```
3. **Build the project**:
```bash
npm run build
```
4. **Set up environment variables** (for image generation):
Create a `.env` file in the project root:
```bash
GOOGLE_AI_KEY=your_google_ai_api_key_here
```
Get your API key from [Google AI Studio](https://makersuite.google.com/app/apikey).
## Usage with Cursor
### Step 1: Start the HTTP Server
The recommended way to use this MCP server is through HTTP mode to avoid ES module compatibility issues:
```bash
npm run start:http
```
This starts the server on `http://localhost:3045` and keeps it running.
### Step 2: Configure MCP in Cursor
Create or update your `cursor-mcp-config.json` file with the following configuration:
```json
{
"mcpServers": {
"local-browser": {
"command": "node",
"args": ["/absolute/path/to/your/project/mcp-http-bridge.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
**Important**:
- Replace `/absolute/path/to/your/project/` with the actual absolute path to your project directory
- The HTTP bridge (`mcp-http-bridge.js`) routes MCP requests to the HTTP server
- Make sure the HTTP server is running before using the tools in Cursor
### Step 3: Restart Cursor
After updating the configuration, restart Cursor to load the new MCP server.
### Step 4: Start Using the Tools
Once configured, you can use the following tools in Cursor:
#### Browser Navigation
- `navigate_to_url` - Navigate to any URL
- `go_back` - Go back in browser history
- `go_forward` - Go forward in browser history
- `refresh_page` - Refresh the current page
#### Screenshots & Visual Capture
- `take_screenshot` - Capture screenshots (full page, viewport, or specific elements)
#### Page Interactions
- `click_element` - Click on elements using CSS selectors
- `type_text` - Type text into input fields
- `scroll_page` - Scroll the page in any direction
- `wait_for_element` - Wait for elements to appear
#### Page Information
- `get_page_info` - Get current page title, URL, and viewport info
#### AI Image Generation
- `generate_image` - Generate custom images using Google Gemini 2.0 Flash Preview
## Quick Start Example
Here's how to get started quickly:
1. **Start the HTTP server**:
```bash
npm run start:http
```
2. **In Cursor, try these commands**:
- "Navigate to google.com and take a screenshot"
- "Generate an image of a sunset over mountains"
- "Click on the search button and type 'hello world'"
## Example Workflow
Here's a typical workflow when testing a website you've created:
1. **Navigate to your local development server**:
```
Use navigate_to_url with "http://localhost:3000"
```
2. **Take a screenshot to see the current state**:
```
Use take_screenshot to capture the full page
```
3. **Interact with your website**:
```
Use click_element to click buttons
Use type_text to fill out forms
Use scroll_page to test scrolling behavior
```
4. **Capture results**:
```
Use take_screenshot again to see changes
```
## Tool Reference
### navigate_to_url
Navigate the browser to a specific URL.
- `url` (required): The URL to navigate to
### take_screenshot
Take a screenshot of the current page.
- `fullPage` (optional): Capture full page vs viewport only
- `selector` (optional): CSS selector to screenshot specific element
### click_element
Click on an element specified by CSS selector.
- `selector` (required): CSS selector of element to click
- `waitFor` (optional): Milliseconds to wait after clicking (default: 1000)
### type_text
Type text into an input field.
- `selector` (required): CSS selector of input element
- `text` (required): Text to type
- `clear` (optional): Clear field before typing (default: true)
### wait_for_element
Wait for an element to appear on the page.
- `selector` (required): CSS selector to wait for
- `timeout` (optional): Timeout in milliseconds (default: 5000)
### scroll_page
Scroll the page.
- `direction` (required): 'up', 'down', 'top', or 'bottom'
- `amount` (optional): Pixels to scroll for up/down (default: 500)
### get_page_info
Get information about the current page (title, URL, viewport size).
### refresh_page
Refresh the current page.
### go_back
Navigate back in browser history.
### go_forward
Navigate forward in browser history.
### generate_image
Generate custom AI images using Google Gemini 2.0 Flash Preview.
- `description` (required): Text description of the image to generate
Generated images are automatically saved to the `generated-images/` directory and can be downloaded via HTTP at `http://localhost:3045/download/{filename}`.
## Development
- **Build**: `npm run build`
- **Development mode**: `npm run dev` (watches for changes)
- **Start**: `npm start` (visible browser) or `npm run start:headless` (background)
- **HTTP Test Server**: `npm run start:http` (visible) or `npm run start:http:headless` (background)
## Browser Behavior
- **Visible Mode**: Browser window opens so you can see what's happening
- **Headless Mode**: Browser runs in background (set `MCP_HEADLESS=true`)
- **Separate Profile**: Uses `/tmp/chrome-mcp-data` to avoid conflicts with your main Chrome
- **Default viewport**: 1280x720 pixels
- **Screenshots**: Returned as base64-encoded PNG images
## Troubleshooting
### Browser doesn't launch
- Ensure Chrome is installed on your system
- Check that no other processes are blocking Chrome
- Try restarting the HTTP server: `npm run start:http`
- Clear Chrome data directory: `rm -rf /private/tmp/chrome-mcp-data`
### Elements not found
- Verify CSS selectors are correct
- Use browser dev tools to test selectors
- Try waiting for elements to load with `wait_for_element`
### MCP Tools not available in Cursor
- Ensure the HTTP server is running: `npm run start:http`
- Check that `cursor-mcp-config.json` has the correct absolute path
- Restart Cursor after configuration changes
- Verify the HTTP bridge file exists: `mcp-http-bridge.js`
### Image generation not working
- Ensure `GOOGLE_AI_KEY` is set in your `.env` file
- Get your API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
- Check that the HTTP server is running (image generation requires HTTP mode)
### Permission issues
- Ensure the MCP server has permission to launch Chrome
- Check file permissions on the built JavaScript files
- On macOS, you may need to allow Chrome in System Preferences > Security & Privacy
## Security Notes
- This server launches a real browser with full system access
- Only use with trusted websites and content
- The browser runs with some security features disabled for automation
- Always run in a controlled environment
## License
MIT License - see LICENSE file for details.
