mcp-server-diwall-browser v0.0.2

mcp-server-diwall-browser v0.0.2

Second release. For Linux.

What it is

An MCP server that gives a language model the eyes and hands of an operator in the operator's own browser. It attaches to a Chromium-family browser that the operator started, with a dedicated profile, through the Chrome DevTools Protocol. The model receives the same screenshot and the same accessibility tree as the operator, and acts in the sessions where the operator is already signed in. Before certain irreversible actions, listed below, a window asks the operator for an answer. Credentials, captures, downloads and the audit journal are kept in an encrypted directory that the operator opens. The conditions of each site stay those of its operator; the server is not a way around them.

How it differs from its neighbours

Chrome DevTools MCP (option --autoConnect) and Playwright MCP (the "Playwright MCP Bridge" extension) can also attach to a browser where you are signed in. This server is built around what happens once it is attached:

• a person answers a window before the actions that the server locks;
• the sensitive fields are masked in the image and withheld from the text;
• a list of allowed origins decides which sites the model reads and acts on;
• credentials, journal, captures and downloads live in an encrypted directory.

What changes in 0.0.2

• A tutorial on the isolation levels, "Choose your level", a page of the project site in English, French, German and Spanish (https://mcp-diwall.davalan.fr/guides/choose-your-level/). It names three levels (reckless, normal, uncompromising), sets the ten routes by which a model could reach a secret or an action next to what closes each, and gives the commands to set up each level, with the output of each command: a second account that holds the encrypted directory, the browser and the server, then a third account for the client and the model. The commands were played block by block, from a clean state, on a Debian 13 workstation under X11 (KDE): 20 blocks, 93 lines of command, every exit code 0; then again on a Debian 13 workstation under GNOME on Wayland, where 19 blocks exit 0 and the block that starts the firewall exits 1 because that service is disabled on that workstation.
• A new subcommand, mcp-server-diwall-browser-setup isolation. Read-only, run from the account of the model, it tries the ten routes, gives a verdict for each and names the level reached. Under a Wayland session it tries the Wayland socket of the operator's session: open from the operator's account, refused by the kernel from the account of the model.
• The server refuses to attach to a debugging port held by another account, and says so with the code debug_endpoint_other_account. setup browser and setup check no longer take any answer on the port for the browser.
• setup close finds the main process of a Chromium whose command line was rewritten as one string; the search of 0.0.1 returned nothing on a real Chromium 156.
• A fifteenth tool, upload_file: it sends files from a deposit directory of the encrypted volume, with a window of the server on every call that shows the file name and its size. A file field takes the file by the protocol; a button or a link that opens the file chooser is pressed with the chooser redirected to the server.
• A click or a key press can declare a send with intent_category: submit, which opens the confirmation window. After a click, a key press or a navigation, the server says the origin the tab was on and the origin it is on when the two differ.
• The ceilings of a session are 1000 actions and 200 pages. When one is reached, the error names the ceiling and the key of the operator profile to raise; raising it acts at the next call.
• The guide the model reads when a session opens has seventeen rules.
• The operator guide describes the window of additional terms of service that Google Chrome opens on a new profile, read on screen in four languages.

What is in 0.0.2, and was in 0.0.1

• Fifteen tools: status, list_tabs, open_tab, navigate, close_tab, observe, scroll, wait, click, fill, select_option, press_key, handle_dialog, save_evidence and upload_file. observe returns a screenshot with numbered marks and the accessibility tree; an action names an element by its mark.
• The server attaches to the debugging port of the browser on the loopback address only, and refuses a port that is reachable beyond it.
• A list of allowed origins, and three policies for an origin that the list does not hold, chosen by the key origin_policy of the operator profile: strict (the default) refuses it; discovery asks you in a window, once per origin; open reads and acts on every public site, local addresses and names staying on the list.
• A confirmation by a person, in a window of the server, before a payment, an irreversible deletion or a change of secret. A denial or an expiry is never retried.
• Masking of the sensitive fields: a password field is covered by a solid rectangle in the image and its value is withheld from the text the model receives.
• An encrypted directory (gocryptfs). There is no mode without it.
• A setup assistant, mcp-server-diwall-browser-setup, that you run yourself in a terminal before the first use, and a second command, mcp-server-diwall-browser-credential-import, that carries a credential file of another format over into the encrypted directory without showing any value.
• Four languages: the README, the operator guide, the architecture document and the manual page man mcp-server-diwall-browser exist in English, French, German and Spanish, and so do the four PDF manuals built from them at the tag; the tutorial on the isolation levels is a page of the site in the same four languages.

Platforms

• Debian 13, Ubuntu 24.04 and 26.04 (.deb): installation, start of the server by an ordinary account, reinstallation over a broken environment and removal validated in containers.
• Fedora 44 (.rpm), openSUSE Leap 16.0 (.rpm) and Arch Linux (.pkg.tar.zst): the same, validated in containers only.
• 64-bit ARM: the .deb of 0.0.1 was installed and tried on a Raspberry Pi 4 Model B. The package of 0.0.2 is of the same kind (all) and has not been tried there.
• Debian 12 and Ubuntu 22.04 are not supported: their Python is older than 3.12.

A container shows neither the confirmation window, nor the mounting of the encrypted directory, nor a browser.

Windows

Linux only. The server does not start on Windows: it relies on Python modules and file permissions that exist only on Unix systems. The part that talks to the browser runs there (measured on Windows Pro with Chrome 156); the rest is not part of 0.0.2.

Tested and not tested

Tested:

• The suite on Debian 13 with Python 3.12.11 and the dependencies of requirements.lock: without a browser, 2276 tests pass, 1 is skipped (it runs as root only) and 632 are deselected; with Google Chrome 156.0.8078.79 (headless, blank temporary profile), 2908 tests pass and 1 is skipped.
• The levels of isolation, measured from the account of the model on two Debian 13 workstations with two accounts besides the operator's, one under X11 (KDE) and one under GNOME on Wayland: at each level the ten routes, the refusal of a port held by another account, and a client of the server (OpenCode with a free model) that filled a credential by credential_ref with the value absent from its output and from the journal.
• The window of upload_file and the window of a declared send, shown by the real zenity and kdialog on a virtual screen; a file field and a file chooser, with Google Chrome 156.0.8078.73 and Chromium 156.0.8078.47: the browser reads a posted file when the form is sent, not when it is posted.
• The window of additional terms of service of Google Chrome 156.0.8078.79 on a new profile, read on screen in English, French, German and Spanish.
• The packages of this version, built from the tag and validated in containers: Debian 13, Ubuntu 24.04 and 26.04, Fedora 44, openSUSE Leap 16.0 and Arch Linux, each with the server started by an ordinary account, the removal, and the reinstallation over a broken environment.

Not tested:

• The .deb of 0.0.2 installed by apt on a real machine, and on the Raspberry Pi 4.
• A person answering the confirmation window on the Raspberry Pi, a Wayland desktop session, and any 64-bit ARM machine other than a Raspberry Pi 4.
• The .rpm and Arch packages outside containers.
• Brave, and Google Chrome builds other than the ones named above; Opera in headless mode fails the perception tests at the read of the view.
• A click on every page layout that puts a role tab inside a link whose label does not take the pointer; the guide says to press Enter on the mark when the click is refused.

The operator guide lists these with the known limits.

Security

• The safeguards are those measured with this version, by the tests and measurements the guide names. A model more recent than the ones tried can find a way around them that no trial has seen.
• The encrypted directory protects as much as its password does: whoever has the password reads its content, and a weak or reused password protects little.
• What the model reads is sent to the provider of the model. This project does not know what a provider keeps.
• To report a vulnerability, do not open a public issue: use the private report of GitHub, https://github.com/RonanDavalan/mcp-server-diwall-browser/security/advisories/new. SECURITY.md says what to expect.

Licenses

mcp-server-diwall-browser is under the MIT license. The Python dependencies (the MCP SDK, websockets, Pillow, pydantic and theirs) are installed by pip on your machine at the versions of requirements.lock; each keeps its own license, and the package does not bundle them.

Install

Package version: 0.0.2-1. Installing a package needs a network connection: it creates a Python virtual environment and installs the dependencies ...

mcp-server-diwall-browser v0.0.1

mcp-server-diwall-browser v0.0.1

First release. For Linux.

What it is

An MCP server that gives a language model the eyes and hands of an operator in the operator's own browser. It attaches to a Chromium-family browser that the operator started, with a dedicated profile, through the Chrome DevTools Protocol. The model receives the same screenshot and the same accessibility tree as the operator, and acts in the sessions where the operator is already signed in. Before certain irreversible actions, listed below, a window asks the operator for an answer. Credentials, captures, downloads and the audit journal are kept in an encrypted directory that the operator opens. The conditions of each site stay those of its operator; the server is not a way around them.

How it differs from its neighbours

Chrome DevTools MCP (option --autoConnect) and Playwright MCP (the "Playwright MCP Bridge" extension) can also attach to a browser where you are signed in. This server is built around what happens once it is attached:

• a person answers a window before the actions that the server locks;
• the sensitive fields are masked in the image and withheld from the text;
• a list of allowed origins decides which sites the model reads and acts on;
• credentials, journal, captures and downloads live in an encrypted directory.

What is in 0.0.1

• Fourteen tools: status, list_tabs, open_tab, navigate, close_tab, observe, scroll, wait, click, fill, select_option, press_key, handle_dialog and save_evidence. observe returns a screenshot with numbered marks and the accessibility tree; an action names an element by its mark.
• The server attaches to the debugging port of the browser on the loopback address only, and refuses a port that is reachable beyond it.
• A list of allowed origins, and three policies for an origin that the list does not hold, chosen by the key origin_policy of the operator profile: strict (the default) refuses it; discovery asks you in a window, once per origin, with Refuser as the default answer, Cette séance or Ajouter à la liste; open reads and acts on every public site, local addresses and names staying on the list. The confirmation applies in the three policies.
• A confirmation by a person, in a window of the server, before a payment, an irreversible deletion or a change of secret. A denial or an expiry is never retried.
• Masking of the sensitive fields: a password field is covered by a solid rectangle in the image and its value is withheld from the text the model receives.
• An encrypted directory (gocryptfs). There is no mode without it.
• A setup assistant, mcp-server-diwall-browser-setup, that you run yourself in a terminal before the first use: check reads your machine, create --temporary makes a throw-away volume in memory, create a durable one, and open, browser and close open the volume, start the browser on its profile and stop both. You type the password yourself at the prompt of gocryptfs; the assistant never reads it.
• A second command, mcp-server-diwall-browser-credential-import, that carries a credential file of another format over into the encrypted directory without showing any value.
• Four languages: the README, the operator guide, the architecture document and the manual page man mcp-server-diwall-browser exist in English, French, German and Spanish.
• Four PDF manuals, one per language, built from those guides at the tag.

Platforms

• Debian 13, Ubuntu 24.04 and 26.04 (.deb): installation, start of the server by an ordinary account, reinstallation over a broken environment and removal validated in containers. The .deb was also installed with apt on a real Debian 13 machine, tried without a screen, then removed and purged.
• 64-bit ARM: the same .deb on a Raspberry Pi 4 Model B (Raspberry Pi OS on Debian 13, aarch64, Chromium 155.0.8059.79), installed and tried on the machine itself, with the complete suite. The browser there is the distribution's Chromium.
• Fedora 44 (.rpm), openSUSE Leap 16.0 (.rpm) and Arch Linux (.pkg.tar.zst): the same, validated in containers only.
• Debian 12 and Ubuntu 22.04 are not supported: their Python is older than 3.12.

A container shows neither the confirmation window, nor the mounting of the encrypted directory, nor a browser.

Windows

Linux only for now. The server does not start on Windows: it relies on Python modules and file permissions that exist only on Unix systems. The part that talks to the browser does work there (measured on Windows Pro with Chrome 156); the rest is planned work and is not part of 0.0.1. The Windows version follows 0.0.1, with its own release notes. No date is promised.

Tested and not tested

Tested:

• The suite on Debian 13 with Python 3.12.11 and the dependencies of requirements.lock: without a browser, 2100 tests pass, 1 is skipped (it runs as root only) and 589 are deselected; with Google Chrome 156.0.8078.47 (headless, blank temporary profile), 2689 tests pass and 1 is skipped.
• The three origin policies, run end to end on a real Chrome with the server started by its entry point, with fake window programs.
• The confirmation window, answered by a person with kdialog 25.04.0 and then with zenity 4.1.90, in Opera 138 and with the operator's own gocryptfs volume mounted: a denial, an acceptance and an expiry each time, six requests, nothing received by the page after a denial or an expiry.
• The server driven through a real MCP client on a local page, and on a public shopping site in Opera 136 with its profile in a throw-away gocryptfs volume.
• A .deb of this version's code installed by apt on a real x86-64 Debian 13 machine and tried without a screen: the manual page in French, the report of mcp-server-diwall-browser-setup check, an MCP handshake and the status tool; then removed and purged. No file of the package was left and the operator's profile was untouched.
• A Raspberry Pi 4 Model B with 8 GB: the .deb installed by apt; the first launch of the setup assistant end to end with the real gocryptfs; the smoke test; the server driven through a real MCP client on a visible Chromium on a virtual X11 screen, with the native confirmation window of zenity opened and left to expire; the complete suite, 2694 tests passed and 1 skipped (five of them are measurements of that machine that the repository does not hold); then the package removed and purged, no file left. On that network the first page a freshly started Chromium loaded took 15 to 26 seconds (the operator guide, section 12, says what was measured).
• A security audit of the tag by two models, each in a fresh session given no list of earlier findings: eight findings were confirmed and corrected before this version.

Not tested:

• The browser, the confirmation window and the creation of an encrypted volume on the x86-64 machine where the .deb was first installed.
• A person answering the confirmation window on the Raspberry Pi, a Wayland desktop session there, and any 64-bit ARM machine other than that Raspberry Pi 4.
• The .rpm and Arch packages outside containers.
• Brave, and Google Chrome builds other than the ones named above; Chrome 154 with its profile in the operator's own encrypted directory.
• The page zoom made by the Ctrl and + keys in a browser that is not headless, and a screen whose scale really is 1.5.
• The setup assistant on a machine that has a swap area (its report is tested on a simulated list).

The operator guide lists these with the known limits.

Security

• The safeguards are those measured with this version, by the tests and measurements the guide names. A model more recent than the ones tried can find a way around them that no trial has seen.
• The encrypted directory protects as much as its password does: whoever has the password reads its content, and a weak or reused password protects little.
• What the model reads is sent to the provider of the model. This project does not know what a provider keeps.
• To report a vulnerability, do not open a public issue: use the private report of GitHub, https://github.com/RonanDavalan/mcp-server-diwall-browser/security/advisories/new. SECURITY.md says what to expect.

Licenses

mcp-server-diwall-browser is under the MIT license. The Python dependencies (the MCP SDK, websockets, Pillow, pydantic and theirs) are installed by pip on your machine at the versions of requirements.lock; each keeps its own license, and the package does not bundle them.

Install

Package version: 0.0.1-1. Installing a package needs a network connection: it creates a Python virtual environment and installs the dependencies in it.

Files: the packages for Debian and Ubuntu (.deb), Fedora and openSUSE Leap (.rpm) and Arch Linux (.pkg.tar.zst), the source tarball and its .sha256, the four PDF manuals and SHA256SUMS. Installation and checksums: https://mcp-diwall.davalan.fr/guides/install/