qutebrowser-mcp

MCP (Model Context Protocol) server for qutebrowser browser automation.

Control qutebrowser from Claude Code or any MCP-compatible client.

Note: Linux only. Uses Unix domain sockets and XDG paths.

Features

• CDP-First Design - Most tools operate on specific tabs via Chrome DevTools Protocol without changing focus

• Tab Management - List, open, close, focus, and move tabs

• Navigation - Go to URLs, back/forward, reload — all targetable to specific tabs

• Screenshots - Capture any tab without switching to it

• JavaScript Execution - Run JS in any tab and get return values

• Authenticated Fetch - Make HTTP requests through the browser's logged-in sessions (cookies or Bearer tokens)

• Bookmarks & History - Access bookmarks, quickmarks, and browsing history

CDP Setup (Recommended)

Most tools use Chrome DevTools Protocol to operate on tabs without changing focus. Enable remote debugging via environment variable:

QTWEBENGINE_REMOTE_DEBUGGING=9222 qutebrowser

Without CDP, tools fall back to IPC which operates on the currently focused tab and may cause tab switches.

Installation

npm install
npm run build

Usage

With Claude Code

Add to your ~/.claude.json:

{
  "mcpServers": {
    "qutebrowser": {
      "command": "node",
      "args": ["/path/to/qutebrowser-mcp/dist/index.js"]
    }
  }
}

Run Directly

npm start

Available Tools

CDP-Enabled Tools

These accept an optional tab parameter (URL or title substring) to target a specific tab via CDP without changing focus. Without tab, they fall back to IPC on the focused tab.

IPC-Only Tools

These use qutebrowser's Unix domain socket for features CDP can't provide.

CDP-Only Tools

These always require CDP and a tab parameter.

browser_fetch vs browser_fetch_auth

• browser_fetch runs fetch() inside the tab's page context. Best for cookie-based auth (same-origin requests).

• browser_fetch_auth intercepts Bearer tokens from the tab's network traffic, then makes the request server-side. Best for token-based auth (e.g. Outlook, which uses MSAuth tokens injected by JavaScript).

How It Works

The server communicates with qutebrowser through two channels:

1. CDP (Chrome DevTools Protocol WebSocket) - Primary channel. Bidirectional communication for JS evaluation, navigation, screenshots, tab close, reload, and network interception. Operates on specific tabs without changing focus.

2. IPC (Unix domain socket) - Secondary channel. Fire-and-forget commands for qutebrowser-specific features (tab open, focus, move, bookmarks, session save).

State is read from:

• Session file (~/.local/share/qutebrowser/sessions/_autosave.yml) - Tab indices, active state, pinned state

• CDP targets - Fresh tab titles and URLs

• SQLite database (~/.local/share/qutebrowser/history.sqlite) - Browsing history

• Config files (~/.config/qutebrowser/) - Bookmarks and quickmarks

Requirements

• Linux (uses Unix domain sockets for IPC)

• Node.js 18+

• qutebrowser running with IPC enabled (default)

• Recommended: qutebrowser started with QTWEBENGINE_REMOTE_DEBUGGING=9222 for CDP support

Respects XDG environment variables (XDG_DATA_HOME, XDG_CONFIG_HOME, XDG_RUNTIME_DIR) with standard fallbacks, so it should work across most Linux distributions.

License

MIT