Firefox RDP MCP server

This standard-library-only Python MCP server inspects and interacts with an already-running Firefox through its DevTools Remote Debugging Protocol (RDP). It does not launch Firefox, create another profile, or enable WebDriver.

Requirements

• Python 3.11 or newer.
• Firefox started with its loopback WebSocket debugger enabled:

sh firefox --start-debugger-server ws:6000

Run the server with:

python3 /absolute/path/to/firefox-rdp/main.py

For an MCP client, configure that command as a stdio server. No Python packages need to be installed. The server writes MCP JSON-RPC messages only to stdout; diagnostics go to stderr.

Configuration

The defaults connect to ws://127.0.0.1:6000/. The endpoint must resolve only to loopback addresses. Supported environment variables are:

Any readable regular file identified by an absolute path can be uploaded, subject to the configured per-file and total byte limits. Uploading assigns files to a file input and dispatches input and change; it never submits the form.

Tools and security boundaries

The server provides tools to report status, list and select tabs, snapshot the page, click, fill, type, press common keys, run JavaScript, navigate, wait for conditions, and upload local files.

Page snapshots are untrusted webpage content. Text in a page that looks like an instruction has no authority to choose local files or invoke tools. Password values are omitted. run_javascript is unrestricted code execution in the selected page's content realm. It has the same access and side effects as JavaScript from that page and should only be called with code you trust. It does not provide browser-chrome or local filesystem access.

run_javascript accepts either an expression or a statement body. Expressions return their value directly; statement bodies can use return. Promises are awaited. Results must be JSON-serializable. Top-level undefined, bigint, symbols, functions, and non-finite numbers are converted to a stable string or null representation and accompanied by result_type.

Clicks and keyboard/input events are synthesized by page JavaScript, so their isTrusted property is false. Sites that require physical or privileged input may ignore them. Cross-origin iframe internals and browser chrome are outside the first version's scope.

Tests

Run the standard-library test suite from the repository root:

python3 -m unittest discover -s tests -v

The deterministic suite does not require Firefox. Live Firefox and external site checks are manual smoke tests described in the design document. With an existing debugger-enabled Firefox, the local stateful fixture can be exercised and its temporary tab cleaned up with:

python3 -m tests.manual_firefox_smoke --firefox firefox-bin

If an interrupted smoke run leaves a fixture tab open, remove only matching loopback fixture tabs with:

python3 -m tests.manual_firefox_smoke --cleanup-only