# 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.