jan-browser

Jan Browser MCP Extension

A lean browser extension that keeps track of automation tabs and exposes them to Jan's Model Context Protocol (MCP) bridge.

Capabilities

• 🔌 Persistent MCP WebSocket bridge
• 🧭 Tab registration helpers used by MCP automation tools
• 🔍 DuckDuckGo and Google search scraping for MCP workflows
• 🖼️ Screenshot, DOM snapshot, and interaction helpers (click, type, fill forms)

Quick Start (5 minutes)

1. Install dependencies

# Clone the repository
git clone https://github.com/janhq/jan-browser-extension.git
cd jan-browser-extension

# Install (npm is sufficient for the minimal build script)
npm install

2. Build the extension

# Build for Chromium-based browsers
npm run build

# Build a Firefox-compatible bundle
npm run build:firefox

3. Load in Chrome

• Open chrome://extensions
• Enable Developer mode
• Click Load unpacked → select the dist folder
• Pin the extension if you want quick visibility

✅ You're ready to use Jan Browser MCP!

4. Use with Jan Desktop

If you have Jan Desktop installed, you can connect it seamlessly with the browser extension:

• Open Jan Desktop → Navigate to Settings → MCP Servers
• Enable the Jan Browser MCP (official) server
• Verify the port matches between Jan and the extension:
  • Default port: 17389
  • In Jan: Set BRIDGE_PORT environment variable if using a custom port
  • In Extension: Click the extension icon → Check Settings → Ensure port matches
• Connect the bridge:
  • Click the extension icon in Chrome
  • Click Connect to establish the WebSocket connection
  • You should see a "Connected" status indicator

Tab Selection:

• Use current tab: Click "Set current tab for browser use" to let Jan control your active tab
• New tab: Jan will automatically open and focus a new tab for automation

✅ Once connected, Jan can use browser automation tools through MCP!

Project Structure

jan-browser/
├── src/
│   ├── background/            # Service worker for MCP routing
│   │   └── index.js
│   ├── content/               # Page data + SERP helpers for MCP tools
│   │   └── index.js
│   ├── constants.js           # Message types, timeouts, defaults
│   ├── popup/                 # React + Tailwind popup UI (Vite entry)
│   ├── mcp-bridge.js          # WebSocket bridge for the local MCP server
│   ├── lib/
│   │   ├── fetch-utils.js     # Async helpers, retries, timeouts
│   │   └── tab-manager.js     # Centralized tab selection & validation
│   ├── search/                # DuckDuckGo/Google helpers
│   └── mcp-tools/             # Browser automation tools (visit, click, etc.)
│
├── mcp-server/                # Optional MCP server (TypeScript)
│   ├── src/
│   │   ├── index.ts           # WebSocket server entry
│   │   └── tools/             # MCP tool implementations
│   └── README.md
│
├── manifest.json              # Chrome MV3 manifest
├── manifest.firefox.json      # Firefox MV3 manifest
├── scripts/build-extension.mjs# Builds React UI + copies runtime scripts
└── package.json               # Scripts & dependencies

Development Workflow

# Extension only
npm run build              # Production build
npm run build:firefox      # Firefox bundle

# MCP server only
npm run build:mcp          # Build TypeScript → JavaScript
npm run dev:mcp            # Watch mode
npm run start:mcp          # Run production build

# Everything together
npm run build:all          # Build extension + MCP server
npm run build:all:firefox  # Firefox manifest + MCP server

Why this refactor?

The popup experience has been rebuilt with React, Tailwind CSS, and shadcn-inspired components so that the extension feels polished while keeping automation logic isolated:

• 🧩 UI lives under src/popup with modern component patterns
• 🧠 Core automation, bridge, and content logic remain framework-free under src/lib, src/mcp-tools, and friends
• 🏗️ scripts/build-extension.mjs compiles the popup via Vite and assembles the final extension bundle

Use the MCP server (mcp-server) if you need a local bridge that exposes the browser tools to an LLM client.