Browser Control MCP

1# Browser Control MCP
2 
3[![Firefox Add-on](./.github/addon_badge.svg)](https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/)
4 
5An MCP server paired with a Firefox browser extension that provides AI assistants with access to tab management, browsing history, and webpage text content.
6 
7## Features
8 
9The MCP server supports the following tools:
10- Open or close tabs
11- Get the list of opened tabs
12- Create tab groups with name and color
13- Reorder opened tabs
14- Read and search the browser's history
15- Read a webpage's text content and links (requires user consent)
16- Find and highlight text in a browser tab (requires user consent)
17 
18## Example use-cases:
19 
20### Tab management
21- *"Close all non-work-related tabs in my browser."*
22- *"Group all development related tabs in my browser into a new group called 'Development'."*
23- *"Rearrange tabs in my browser in an order that makes sense."*
24- *"Close all tabs in my browser that haven't been accessed within the past 24 hours"*
25 
26### Browser history search
27- *"Help me find an article in my browser history about the Milford track in NZ."*
28- *"Open all the articles about AI that I visited during the last week, up to 10 articles, avoid duplications."*
29 
30### Browsing and research 
31- *"Open hackernews in my browser, then open the top story, read it, also read the comments. Do the comments agree with the story?"*
32- *"In my browser, use Google Scholar to search for papers about L-theanine in the last 3 years. Open the 3 most cited papers. Read them and summarize them for me."*
33- *"Use Google search in my browser to look for flower shops. Open the 10 most relevant results. Show me a table of each flower shop with location and opening hours."*
34 
35## Comparison to web automation MCP servers
36 
37The MCP server and Firefox extension combo is designed to be more secure than web automation MCP servers, enabling safer use with the user's personal browser.
38 
39* It does not support web page modification, page interactions, or arbitrary scripting.
40* Reading webpage content requires the user's explicit consent in the browser for each domain. This is enforced at the extension's manifest level.
41* It uses a local-only connection with a shared secret between the MCP server and extension.
42* No remote data collection or tracking.
43* It provides an extension-side audit log for tool calls and tool enable/disable configuration.
44* The extension includes no runtime third-party dependencies.
45 
46**Important note**: Browser Control MCP is still experimental. Use at your own risk. You should practice caution as with any other MCP server and authorize/monitor tool calls carefully.
47 
48## Installation
49 
50### Option 1: Install the Firefox and Claude Desktop extensions
51 
52The Firefox extension / add-on is [available on addons.mozilla.org](https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/). You can also download and open the latest pre-built version from this GitHub repository: [browser-control-mcp-1.5.0.xpi](https://github.com/eyalzh/browser-control-mcp/releases/download/v1.5.0/browser-control-1.5.0.xpi). Complete the installation based on the instructions in the "Manage extension" page, which will open automatically after installation.
53 
54The add-on's "Manage extension" page will include a link to the Claude Desktop DXT file. You can also download it here: [mcp-server-v1.5.1.dxt](
55https://github.com/eyalzh/browser-control-mcp/releases/download/v1.5.1/mcp-server-v1.5.1.dxt). After downloading the file, open it or drag it into Claude Desktop's settings window. Make sure to enable the DXT extension after installing it. This will only work with the latest versions of Claude Desktop. If you wish to install the MCP server locally, see the MCP configuration below.
56 
57### Option 2: Build from code
58 
59To build from code, clone this repository, then run the following commands in the main repository directory to build both the MCP server and the browser extension.
60```
61npm install
62npm run build
63```
64 
65#### Installing a Firefox Temporary Add-on 
66 
67To install the extension on Firefox as a Temporary Add-on:
68 
691. Type `about:debugging` in the Firefox URL bar
702. Click on "This Firefox"
713. click on "Load Temporary Add-on..."
724. Select the `manifest.json` file under the `firefox-extension` folder in this project
735. The extension's preferences page will open. Copy the secret key to your clipboard. It will be used to configure the MCP server.
74 
75Alternatively, to install a permanent add-on, you can install the [Browser Control MCP on addons.mozilla.org](https://addons.mozilla.org/en-US/firefox/addon/browser-control-mcp/) and then configure the MCP Server as detailed below.
76 
77If you prefer not to run the extension on your personal Firefox browser, an alternative is to download a separate Firefox instance (such as Firefox Developer Edition, available at https://www.mozilla.org/en-US/firefox/developer/).
78 
79 
80#### MCP Server configuration
81 
82After installing the browser extension, add the following configuration to your mcpServers configuration (e.g. `claude_desktop_config.json` for Claude Desktop):
83```json
84{
85    "mcpServers": {
86        "browser-control": {
87            "command": "node",
88            "args": [
89                "/path/to/repo/mcp-server/dist/server.js"
90            ],
91            "env": {
92                "EXTENSION_SECRET": "<secret_on_firefox_extension_options_page>",
93                "EXTENSION_PORT": "8089" 
94            }
95        }
96    }
97}
98```
99Replace `/path/to/repo` with the correct path.
100 
101Set the EXTENSION_SECRET to the value shown on the extension's preferences page in Firefox (you can access it at `about:addons`). You can also set the EXTENSION_PORT environment variable to specify the port that the MCP server will use to communicate with the extension (default is 8089).
102 
103It might take a few seconds for the MCP server to connect to the extension.
104 
105##### Configure the MCP server with Docker
106 
107Alternatively, you can use a Docker-based configuration. To do so, build the mcp-server Docker image:
108```
109docker build -t browser-control-mcp .
110```
111 
112and use the following mcpServers configuration:
113 
114```json
115{
116    "mcpServers": {
117        "browser-control": {
118            "command": "docker",
119            "args": [
120                "run",
121                "--rm",
122                "-i",
123                "-p", "127.0.0.1:8089:8089",
124                "-e", "EXTENSION_SECRET=<secret_from_extension>",
125                "-e", "CONTAINERIZED=true",
126                "browser-control-mcp"
127            ]
128        }
129    }
130}
131```
132 
133