MCP Browser (MCP fetch for protected web resources)

Enables GitHub Copilot to fetch protected web pages - handles login-protected web pages, corporate SSO, and anti-crawler restrictions that normal fetching can't handle. Uses your Chrome/Edge browser session via DevTools Protocol.

🚀 Installation Options

Option 1: VS Code Extension (Easiest - One Click)

From VS Code Marketplace:

code --install-extension cherchyk.mcpbrowser

Or search "MCPBrowser" in VS Code Extensions view.

From GitHub Release: Download from GitHub Releases:

code --install-extension mcpbrowser-0.2.15.vsix

The extension automatically:

• Installs the MCPBrowser npm package globally
• Configures mcp.json for GitHub Copilot
• Complete one-click setup - no manual steps needed

📦 View on Marketplace

Option 2: npm Package (Recommended for Manual Setup)

Published on npm as mcpbrowser v0.2.15.

Add to your mcp.json:

"MCPBrowser": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "mcpbrowser@latest"],
  "description": "Use AUTOMATICALLY on 401/403 errors, login pages, SSO prompts, anti-bot blocks, OR when you think loading via real browser would be beneficial (JavaScript-heavy sites, dynamic content, SPAs). First domain request: ask user confirmation (browser opens for auth). Subsequent same-domain: use automatically (session preserved). Returns HTML from authenticated Chrome session. Handles Microsoft, GitHub, AWS, Google, corporate sites."
}

mcp.json Location:

• Windows: %APPDATA%\Code\User\mcp.json
• Mac/Linux: ~/.config/Code/User/mcp.json

Option 3: MCP Registry

Available in the MCP Registry as io.github.cherchyk/browser v0.2.15.

Search for "browser" in the registry to find configuration instructions.

Option 4: Clone from GitHub (Development)

git clone https://github.com/cherchyk/MCPBrowser.git
cd MCPBrowser
npm install
copy .env.example .env  # optional: set Chrome overrides

Option 2: Install via npx (when published to npm)

npx mcpbrowser

Prereqs

• Chrome or Edge installed.
• Node 18+.

Run (automatic via Copilot)

• Add the MCP server entry to VS Code settings (github.copilot.chat.modelContextProtocolServers, see below). Copilot will start the server automatically when it needs the tool—no manual launch required.
• On first use, the server auto-launches Chrome/Edge with remote debugging if it cannot find an existing DevTools endpoint. Defaults: port 9222, user data dir %LOCALAPPDATA%/ChromeAuthProfile. Override with CHROME_PATH, CHROME_USER_DATA_DIR, or CHROME_REMOTE_DEBUG_PORT.
• The old scripts/start-all.ps1 launcher was removed; Chrome startup is handled inside the MCP server.

Manual start (optional)

Only if you want to run it yourself (Copilot already starts it when configured):

npm run mcp

Or manually:

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\ChromeAuthProfile"

Set CHROME_PATH if auto-detect fails; override profile with CHROME_USER_DATA_DIR, port with CHROME_REMOTE_DEBUG_PORT.

(Optional) Local runner

There is no local LLM runner now; Copilot provides the LLM and calls this MCP tool. If you need a standalone agent later, we can add one that reuses the fetch logic.

Configure in VS Code (GitHub Copilot)

Step 1: Locate your mcp.json file

• Windows: %APPDATA%\Code\User\mcp.json
• Linux/Mac: ~/.config/Code/User/mcp.json

Step 2: Add MCPBrowser server configuration

Add this entry to your mcp.json file under the "servers" section:

"MCPBrowser": {
    "type": "stdio",
    "command": "node",
    "args": ["<PATH_TO_MCPBROWSER>/src/mcp-browser.js"],
    "description": "Use AUTOMATICALLY on 401/403 errors, login pages, SSO prompts, anti-bot blocks, OR when you think loading via real browser would be beneficial (JavaScript-heavy sites, dynamic content, SPAs). First domain request: ask user confirmation (browser opens for auth). Subsequent same-domain: use automatically (session preserved). Returns HTML from authenticated Chrome session. Handles Microsoft, GitHub, AWS, Google, corporate sites."
}

Replace <PATH_TO_MCPBROWSER> with the full path where you cloned this repository, for example:

• Windows: "D:/dev/MCPBrowser/src/mcp-browser.js"
• Linux/Mac: "/home/user/MCPBrowser/src/mcp-browser.js"

Step 3: Reload VS Code

Restart VS Code or reload the window for the changes to take effect.

Step 4: Verify

In Copilot Chat, you should see the MCPBrowser server listed. Ask it to fetch an authenticated URL and it will drive your signed-in Chrome session.

How it works

• Tool fetch_webpage_protected (inside the MCP server) drives your live Chrome (DevTools Protocol) so it inherits your auth cookies, returning html (truncated up to 2M chars) for analysis.
• Smart confirmation: Copilot asks for confirmation ONLY on first request to a new domain - explains browser will open for authentication. Subsequent requests to same domain work automatically (session preserved).
• Domain-aware tab reuse: Automatically reuses the same tab for URLs on the same domain, preserving authentication session. Different domains open new tabs.
• Automatic web page fetching: Waits for network idle (networkidle0) by default, ensuring JavaScript-heavy web pages (SPAs, dashboards) fully load before returning content.
• Automatic auth detection: Detects ANY authentication redirect (domain changes, login/auth/sso/oauth URLs) and waits for you to complete sign-in, then returns to target web page.
• Universal compatibility: Works with Microsoft, GitHub, AWS, Google, Okta, corporate SSO, or any authenticated site.
• Smart timeouts: 60s default for web page fetch, 10 min for auth redirects. Tabs stay open indefinitely for reuse (no auto-close).
• GitHub Copilot's LLM invokes this tool via MCP; this repo itself does not run an LLM.

Auth-assisted fetch flow

• Copilot can call with just the URL, or with no params if you set an env default (DEFAULT_FETCH_URL or MCP_DEFAULT_FETCH_URL). By default tabs stay open indefinitely for reuse (domain-aware).
• First call opens the tab and leaves it open so you can sign in. No extra params needed.
• After you sign in, call the same URL again; tab stays open for reuse. Set keepPageOpen: false to close immediately on success.
• Optional fields (authWaitSelector, waitForSelector, waitForUrlPattern, etc.) are available but not required.

Configuration

• .env: optional overrides for CHROME_WS_ENDPOINT, CHROME_REMOTE_DEBUG_HOST/PORT, CHROME_PATH, CHROME_USER_DATA_DIR.
• To use a specific WS endpoint: set CHROME_WS_ENDPOINT from Chrome chrome://version DevTools JSON.

Tips

• Universal auth: Works with ANY authenticated site (Microsoft, GitHub, AWS, Google, corporate intranets, SSO, OAuth, etc.)
• No re-authentication needed: Automatically reuses the same tab for URLs on the same domain, keeping your auth session alive across multiple web page fetches
• Automatic web page fetching: Tool waits for web pages to fully load (default 60s timeout, waits for network idle). Copilot should trust the tool and not retry manually.
• Auth redirect handling: Auto-detects auth redirects by monitoring domain changes and common login URL patterns (/login, /auth, /signin, /sso, /oauth, /saml)
• Tabs stay open: By default tabs remain open indefinitely for reuse. Set keepPageOpen: false to close immediately after successful fetch.
• Smart domain switching: When switching domains, automatically closes the old tab and opens a new one to prevent tab accumulation
• If you hit login web pages, verify Chrome instance is signed in and the site opens there.
• Use a dedicated profile directory to avoid interfering with your daily Chrome.
• For heavy web pages, add waitForSelector to ensure post-login content appears before extraction.