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

pnpm install

2. Build the Project

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

{
  "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:

   /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:

pnpm run watch

Running Standalone

You can also run the server standalone for testing:

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:

   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

2. Check if port 9222 is available:

   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:

   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:

   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 - MCP SDK
• chrome-launcher - Chrome launcher
• chrome-remote-interface - Chrome DevTools Protocol client