
Browser extension & Python WebSocket bridge to connect web-based AI interfaces with local Model
Browser extension & Python WebSocket bridge to connect web-based AI interfaces with local Model Context Protocol (MCP) servers.
·
Use your local MCP servers with ChatGPT, Gemini, Claude Web and DeepSeek: no API keys, no extra subscriptions.
Web MCP Bridge lets the free web versions of ChatGPT, Gemini, Claude and DeepSeek use tools on your own computer: read files, control programs, query your data… with no API keys and no extra subscriptions. You approve every action.
[!IMPORTANT] Only connect MCP servers you trust. A tool with filesystem access can read whatever you allow it to.
Jump to: Install · First use · Add my MCPs · Troubleshooting
Two pieces work together:
| Piece | What it is | Where it lives |
|---|---|---|
| 🌐 The extension | Installed in your browser. It reads what the AI asks for and shows you the buttons and permissions. | Chrome, Edge or Brave |
| 🌉 The bridge | A small Python program that connects the extension to your tools (MCP servers). | Your computer, in the background |
flowchart LR
A["💬 Chat<br/>ChatGPT · Gemini · Claude · DeepSeek"] <--> B["🌐 Extension"]
B <-->|"local WebSocket"| C["🌉 Bridge (Python)"]
C <--> D["🧰 Your MCP tools"]🔒 Everything happens on your computer. Nothing is sent to third-party servers.
| Requirement | How to check |
|---|---|
| Chrome, Edge or Brave (version 116 or newer) | Menu → About. |
| Python 3.9 or newer | Open a terminal and type python --version. If missing, get it from python.org/downloads and tick “Add Python to PATH” during setup. |
| This project downloaded | Green Code → Download ZIP button on GitHub, then unzip (or git clone). Keep it in a permanent folder: the extension loads from there, so don't delete or move it afterwards. |
Optional: Node.js, if you'll use MCP servers launched with npx (for example the filesystem one).
Step 1 · Install the launcher (once)
Open the server folder and double-click install.cmd. Wait until it says Done.
It does three things for you: installs what's missing (websockets), makes the bridge start automatically when you log in, and starts it right now.
Step 2 · Load the extension in your browser
chrome://extensions in the address bar (Edge: edge://extensions).manifest.json).Step 3 · Check everything is green Open the extension icon: the top should say “Puente conectado” (bridge connected) with a green dot and your servers below.
Done! Continue with Your first time.
python3 server/install_service.pyIt installs what's needed and makes the bridge start with your session (launchd on macOS, systemd on Linux). Then load the extension as in Step 2. The popup's Start / Stop buttons need the launcher, which is currently Windows-only. On macOS/Linux the bridge still works and restarts itself if it crashes.
No terminal needed for everyday use. In the popup, bridge card:
| Button | What it does |
|---|---|
| Start | Turns the bridge on (if it was off). |
| Stop | Turns it off and keeps it off until you start it again (even after rebooting your PC). |
| Restart | Closes and reopens it. Use it after changing something or if it got stuck. |
| Edit servers.json | Opens the file that lists your MCPs. It reloads by itself when you save. |
💡 Header switch vs. “Stop”. The big switch in the header only makes the extension stop acting (the icon shows
OFF). “Stop” closes the program on your PC.
If Start/Stop is greyed out, the launcher is missing: double-click server/install.cmd.
The project ships with a demo server (demo) so you can try it without installing anything else.
By default permission is “Ask every time”: nothing runs unless you approve it. You can change it per server or for all of them.
Your servers are defined in server/servers.json (created automatically on install). Each one needs a name, a unique port and the command that starts it:
{
"servers": [
{ "name": "demo", "port": 8090, "command": ["python", "server/examples/demo_mcp_server.py"] },
{ "name": "my-mcp", "port": 8081, "command": ["python", "-m", "my_mcp_server"] },
{ "name": "files", "port": 8082, "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Users/you/Documents"] }
]
}server/servers.example.json."disabled": true./ (C:/Users/...) instead of \.| Symptom | Fix |
|---|---|
| Popup says “Puente apagado” (bridge off) | Click Start. If the button is greyed out, double-click server/install.cmd. |
| “Falta el lanzador” (launcher missing) | Normal the first time: run server/install.cmd once. |
python is not recognized | Reinstall Python ticking Add Python to PATH, or try py instead of python. |
| “Port in use” (8080, 8090…) | Click Restart. If it persists, change that server's port in servers.json. |
A server shows an error (e.g. astrax-mcp) | It's just an example: if you don't have it installed, delete it from servers.json or add "disabled": true. |
| Red notice “servers.json tiene un error” | A comma or quote is misplaced. Fix it and save: the bridge reloads by itself. |
| The chat doesn't react / panel missing | Reload the tab (F5) and make sure the header switch is on. If the site changed its UI, open an issue. |
| I moved or renamed the project folder | Run server/install.cmd again and click ⟳ in chrome://extensions. |
| I want to remove everything | python server/install_service.py --uninstall and remove the extension. |
Still stuck? Tell us in the Telegram channel or open an issue.
| Platform | Status | Adapter |
|---|---|---|
| ✅ Supported | adapters/chatgpt.js | |
| ✅ Supported | adapters/gemini.js | |
| ✅ Supported | adapters/claude.js | |
| ✅ Supported | adapters/deepseek.js | |
| · | 🗺️ Roadmap | Contribute |
| Skill | What it does | |
|---|---|---|
| Context control | Register many servers, 1 active by default (up to 5). Only active servers' tools reach the model; the popup shows the approximate token cost. | |
| Per-MCP permissions | 3-state selector — Allow always · Ask every time · Don't allow — global and per server, in the popup and the in-page panel. | |
| Nothing is dropped | Images, audio and binary resources are attached to the chat as real files; long text is attached in full instead of truncated. | |
| No preinstalled MCP | Add your own, or the bundled demo server with one click. | |
| Reliable in the background | No step relies on page timers (throttled when hidden); delivery is verified and retried. | |
| The AI doesn't forget | A one-line reminder per message plus periodic full re-injection. | |
| ≈ 50 % fewer tokens | Tools are described as name(param: type) signatures instead of JSON Schema. | |
| ~40 lines per platform | A new platform is just a set of selectors. | |
| Locked down | The Python bridge listens on 127.0.0.1, only accepts chrome-extension:// origins and supports a token. Websites can't reach your tools. | |
| No duplicates, auto-reconnect | Per-call IDs, exponential backoff, keep-alive for the MV3 Service Worker, call history, light/dark UI. | |
| Badly escaped JSON never hangs the chat | Windows paths with \, raw newlines, unescaped quotes or trailing commas are repaired. If it still can't be read, the server / name / arguments flags are found separately and each argument is extracted using the tool schema. If nothing works, the AI is told the exact reason instead of waiting forever. | |
| Servers detected automatically | The extension reads server/servers.json through the bridge's control port (http://127.0.0.1:8099/servers): new MCPs show up on their own and removed ones disappear. A server you delete by hand stays deleted. | |
| No more "port 8080 in use" | --restart / --stop / --status / --reload, hot reload when servers.json is saved, and a restart that closes a previous bridge by itself. | |
| Reconnect without duplicates | If the server was down before the call was sent, the extension waits for the reconnection and retries. If the AI sends several calls in one message, it's told only the first one ran. |
Everything above can also be done from the terminal.
# Launcher (Windows): start, stop and restart
python server/start_bridge_loop.pyw --ctl start | stop | restart | status | quit
# Bridge directly
python server/mcp_ws_bridge.py --config server/servers.json --restart # restart (closes the old one even if it holds :8080)
python server/mcp_ws_bridge.py --config server/servers.json --status # status of every server
python server/mcp_ws_bridge.py --config server/servers.json --reload # re-read servers.json
python server/mcp_ws_bridge.py --config server/servers.json --stop # stop the bridge
python server/install_service.py --uninstall # remove auto-startOn Windows you can also double-click server\restart_bridge.cmd / server\bridge_status.cmd.
| Port | Purpose |
|---|---|
8080, 8081… | One port per MCP server (you define them in servers.json). |
8099 | Bridge control (/servers, /reload, /restart, /shutdown). |
8098 | Launcher (/start, /stop, /restart, /status). Configurable with "launcher_port". |
--config reloads it instead of failing with "port in use".--restart only closes mcp_ws_bridge processes; if another program owns the port it tells you which and leaves it alone.servers.json accepts a BOM (added by PowerShell), a top-level "control_port" / "launcher_port" and "disabled": true per server.python server/mcp_ws_bridge.py --port 8080 --name demo -- python server/examples/demo_mcp_server.py{ "mcp_call": { "server": "server_name", "name": "tool_name", "arguments": { "arg1": "value" } } }Results come back as:
[MCP_RESULT server="…" tool="…" status="ok|error|rejected"]
…
[/MCP_RESULT][!NOTE] The content of
MCP_RESULTis presented to the AI as data, not instructions (prompt-injection mitigation).
The parser reads the call in three layers: 1) strict JSON, 2) repaired JSON (backslash paths, raw newlines, unescaped or typographic quotes, trailing commas) and 3) flags: server, name and arguments are located separately and each argument is extracted by name using the tool schema. A call is only accepted if the server and tool exist among the active MCPs and the message isn't cut off.
If the AI clearly tried to call a tool but the block can't be read, the extension answers (max. 3 consecutive notices) instead of leaving the chat waiting:
[MCP_RESULT server="bridge" tool="mcp_call" status="format_error"]
Nothing was executed: your mcp_call block could not be read. Reason: invalid escape sequence (... near: ...)
[/MCP_RESULT][!NOTE] A path such as
C:\new\testis ambiguous for any JSON parser (\n,\t), which is why the prompt always asks for/in paths.
With several large MCPs at once (e.g. 329 tools) the full prompt was over 100,000 characters and froze the browser ("page unresponsive", mostly on Gemini). Now, when there are more than 40 active tools, the prompt (~2,000 characters) only lists the connected servers with their tool and page counts, and the AI queries them with a local bridge tool (it never reaches any MCP, needs no permission and is read-only):
{"mcp_call":{"server":"wmb","name":"list_tools","arguments":{"server":"rea","page":2}}}arguments | Result |
|---|---|
| (empty) | Server summary: tool count, pages and most common name prefixes |
server, page | A page of 50 tools (name(params): description) and how to ask for the next one |
query (+ optional server) | Word search over name and description, also paginated |
server, tool | Full signature and description of one tool |
limit | Tools per page (1 – 50) |
The AI pages or searches until it finds the tool, then calls it with its real server; if it already knows the exact name it can call it directly. Small servers are still listed in full in the prompt, and with few tools everything works exactly as before. The threshold and page size are the catalogThreshold (40; 0 = always catalog) and catalogPageSize (50) settings. The tool list is also no longer re-sent to the tab every 10 s when unchanged, and long texts are typed into the chat yielding to the browser every 25 lines.
| Risk | Mitigation |
|---|---|
A website opens ws://localhost and runs tools | The bridge rejects any Origin that isn't a browser extension. |
| The AI runs unwanted actions | “Ask every time” is the default; “Allow always” is an explicit choice per MCP (or global); “Don't allow” blocks the MCP. |
| Hidden instructions in results (prompt injection) | The prompt marks MCP_RESULT as data only, and you see each call before it runs. |
| Network exposure | Listens on 127.0.0.1 only; optional token (--token). |
A website reads or shuts down the control (:8099) or launcher (:8098) ports | They only accept extension Origins and local Hosts; state-changing routes require POST; --restart only closes real bridge processes. |
Selectors live at the top of each adapter (content_scripts/adapters/*.js). Add the new selector at the start of the matching list (composer, sendButton, assistantMessages, stopButton) and open an issue: it's usually a one-line fix.
npm test # syntax, parser, prompt builder and bridge integration tests
npm run pack # dist/web-mcp-bridge.zipAstrax is open source and grows with its community. You're welcome to open issues, send pull requests, suggest ideas, try Astrax on other systems or MCP clients, and report bugs. Read CONTRIBUTING.md to get started — new adapters are the best first contribution.
Please also read our Code of Conduct before taking part, and report security issues privately by following our Security Policy (never in a public issue).
[!TIP] Looking for more MCP servers to plug into the bridge? Browse the community-curated Awesome MCP Servers list.
If you find the project useful, leave a ⭐ on the repository and subscribe to the channel.
Made with 💙 by Rufus · @AstraxOf · astrabots.pro
This repo does not document an install step we could read. Check the README on GitHub.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/web-mcp-bridge to learn what the "Web MCP Bridge" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
This server doesn't publish a machine-readable tool manifest, and it doesn't expose a public endpoint we could ask. Connect the server locally to see what it exposes.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/web-mcp-bridge)Nothing comparable is listed yet.
v1.8.0Web MCP Bridge v1.8.0Release notesv1.7.2Web MCP Bridge v1.7.2Release notesv1.7.0Web MCP Bridge v1.7.0Release notesv1.6.0Web MCP Bridge v1.6.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "web-mcp-bridge" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.