chrome-mcp/README.md

Model Context Protocol (MCP) server for controlling Google Chrome browser on macOS. Enables AI assistants like Claude to automate Chrome via DevTools Protocol.

# Chrome MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to control and interact with Google Chrome on macOS.

## Features

This MCP server provides comprehensive Chrome browser control capabilities:

- **Navigation**: Navigate to URLs, go back/forward, reload pages
- **Tab Management**: Open new tabs, close tabs, list all tabs
- **Page Interaction**: Click elements, type into inputs, execute JavaScript
- **Page Inspection**: Get page title, URL, HTML content, visible text
- **Screenshots**: Capture page screenshots
- **Full DevTools Protocol**: Access Chrome DevTools Protocol for advanced automation

## Prerequisites

- **Node.js**: Version 18.0.0 or newer
- **Google Chrome**: Latest stable version
- **macOS**: Required for AppleScript-based tab management features
- **Claude Desktop**: For MCP integration

## Installation

### 1. Install Dependencies

```bash
pnpm install
```

### 2. Build the Project

```bash
pnpm run build
```

## Setup for Claude Desktop

### 1. Configure Claude Desktop

Add the following to your Claude Desktop configuration file located at:
`~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "chrome": {
      "command": "node",
      "args": ["/Users/Apple/Documents/GitHub/chrome-mcp/build/index.js"]
    }
  }
}
```

> **Note**: Replace the path with the actual absolute path to your `build/index.js` file.

### 2. Grant Necessary Permissions

#### Enable Remote Debugging in Chrome

1. Open Google Chrome
2. Go to **View** → **Developer** → **Allow JavaScript from Apple Events**
3. Alternatively, launch Chrome with remote debugging:
   ```bash
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   ```

#### Grant Accessibility Permissions (for AppleScript features)

1. Open **System Preferences** → **Security & Privacy** → **Privacy** → **Accessibility**
2. Click the lock icon to make changes
3. Add your terminal application (Terminal, iTerm2, etc.)
4. Enable the checkbox

### 3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop to load the MCP server.

## Available Tools

Once configured, Claude will have access to these tools:

| Tool Name | Description |
|-----------|-------------|
| `chrome_navigate` | Navigate to a specific URL |
| `chrome_get_current_url` | Get the current page URL |
| `chrome_get_title` | Get the page title |
| `chrome_get_content` | Get the full HTML content |
| `chrome_get_visible_text` | Get visible text from the page |
| `chrome_execute_script` | Execute JavaScript code |
| `chrome_click` | Click an element by CSS selector |
| `chrome_type` | Type text into an input field |
| `chrome_screenshot` | Take a screenshot (returns base64 PNG) |
| `chrome_open_new_tab` | Open a new tab |
| `chrome_close_tab` | Close the current tab |
| `chrome_list_tabs` | List all open tabs |
| `chrome_reload` | Reload the current page |
| `chrome_go_back` | Navigate back in history |
| `chrome_go_forward` | Navigate forward in history |

## Usage Examples

Once integrated with Claude Desktop, you can give natural language commands like:

- "Navigate to google.com in Chrome"
- "Take a screenshot of the current page"
- "Click the search button on the page"
- "Get all the visible text from this webpage"
- "Execute some JavaScript to change the background color"
- "Open a new tab and go to github.com"
- "List all my open Chrome tabs"

## Development

### Watch Mode

To automatically rebuild on file changes:

```bash
pnpm run watch
```

### Running Standalone

You can also run the server standalone for testing:

```bash
pnpm start
```

The server will communicate via stdin/stdout following the MCP protocol.

## Architecture

This project consists of two main components:

1. **ChromeController** (`src/chrome-controller.ts`): 
   - Manages Chrome DevTools Protocol (CDP) connections
   - Implements browser automation methods
   - Uses AppleScript for Mac-specific features (tab management)

2. **MCP Server** (`src/index.ts`):
   - Implements the Model Context Protocol server
   - Exposes Chrome control methods as MCP tools
   - Handles communication with Claude Desktop

## Troubleshooting

### Chrome Connection Issues

If the server can't connect to Chrome:

1. Ensure Chrome is running with remote debugging:
   ```bash
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   ```

2. Check if port 9222 is available:
   ```bash
   lsof -i :9222
   ```

### AppleScript Permission Denied

If tab management features fail:

1. Enable "Allow JavaScript from Apple Events" in Chrome
2. Grant accessibility permissions to your terminal app
3. Try running the command manually to test:
   ```bash
   osascript -e 'tell application "Google Chrome" to activate'
   ```

### MCP Server Not Showing in Claude

1. Verify the path in `claude_desktop_config.json` is absolute
2. Check that the build was successful (`build/index.js` exists)
3. Look at Claude Desktop logs for errors:
   ```bash
   tail -f ~/Library/Logs/Claude/mcp*.log
   ```

## Security Considerations

- This server has full control over your Chrome browser
- Only use it with trusted AI assistants
- Be cautious when executing arbitrary JavaScript
- The server can access any content visible in Chrome

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Credits

Built using:
- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk) - MCP SDK
- [chrome-launcher](https://github.com/GoogleChrome/chrome-launcher) - Chrome launcher
- [chrome-remote-interface](https://github.com/cyrus-and/chrome-remote-interface) - Chrome DevTools Protocol client