MCP Browser (MCP fetch for protected web resources)

Enables Claude Code, GitHub Copilot, and Claude Desktop 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.3.1.vsix

The extension automatically:

• Installs the MCPBrowser npm package globally
• Configures mcp.json for Claude Code & 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.3.1.

Add to your mcp.json:

"MCPBrowser": {
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "mcpbrowser@latest"],
  "description": "Web page fetching via browser for sites requiring authentication, anti-bot protection, or JavaScript rendering. Use when standard HTTP requests fail for: (1) auth-required pages (401/403, SSO, corporate intranets), (2) anti-bot verification (CAPTCHA, Cloudflare), (3) JavaScript-heavy sites (SPAs, dynamic content). Opens a browser where the user can authenticate, then automatically extracts content."
}

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.3.1.

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

Option 4: Claude Desktop

Add to your Claude Desktop config file:

Config Location:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "MCPBrowser": {
      "command": "npx",
      "args": ["-y", "mcpbrowser@latest"]
    }
  }
}

Restart Claude Desktop after configuration.

Option 5: Clone from GitHub (Development)

git clone https://github.com/cherchyk/MCPBrowser.git
cd MCPBrowser/MCPBrowser  # Navigate to MCP server directory
npm install

Prereqs

• Chrome or Edge installed.
• Node 18+.

Run (automatic via AI assistants)

• Add the MCP server entry to your AI assistant's config (see installation options above). The AI assistant 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.
• Chrome startup is handled inside the MCP server.

Manual start (optional)

Only if you want to run it yourself (AI assistants already start 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; AI assistants (Claude Code, GitHub Copilot, Claude Desktop) provide the LLM and call this MCP tool. If you need a standalone agent later, we can add one that reuses the fetch logic.

Configure in VS Code (Claude 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": "Web page fetching via browser for sites requiring authentication, anti-bot protection, or JavaScript rendering. Use when standard HTTP requests fail for: (1) auth-required pages (401/403, SSO, corporate intranets), (2) anti-bot verification (CAPTCHA, Cloudflare), (3) JavaScript-heavy sites (SPAs, dynamic content). Opens a browser where the user can authenticate, then automatically extracts content."
}

Replace <PATH_TO_MCPBROWSER> with the full path to the MCP server directory in the cloned repository, for example:

• Windows: "D:/dev/MCPBrowser/MCPBrowser/src/mcp-browser.js"
• Linux/Mac: "/home/user/MCPBrowser/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 Claude Code or 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 (inside the MCP server) drives your live Chrome/Edge (DevTools Protocol) so it inherits your auth cookies, returning html (truncated up to 2M chars) for analysis.
• Smart confirmation: AI assistant 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 page loading: Waits for network idle (networkidle0) by default, ensuring JavaScript-heavy 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 page.
• Universal compatibility: Works with ANY authenticated site - corporate intranets, SSO, OAuth, SAML, login pages, etc.
• Smart timeouts: 60s default for page fetch, 10 min for auth redirects. Tabs stay open indefinitely for reuse (no auto-close).
• The AI assistant's LLM invokes this tool via MCP; this repo itself does not run an LLM.

🎯 Interactive Features (NEW!)

MCPBrowser now supports human-like interaction with web pages! You can click buttons, fill forms, and interact with dynamic content just like a human would.

Available Tools

1. click_element - Click on page elements

Click on any element - buttons, links, divs with onclick handlers, or any clickable element.

Parameters:

• url (required): URL of the page (must be already loaded via fetch_webpage)
• selector (optional): CSS selector for the element (e.g., #submit-btn, .login-button)
• text (optional): Text content to search for if selector not provided (e.g., "Sign In", "Submit")
• timeout (optional): Maximum wait time in milliseconds (default: 30000)

Example:

// Click by selector
{ url: "https://example.com", selector: "#login-button" }

// Click by text content
{ url: "https://example.com", text: "Sign In" }

2. type_text - Type text into input fields

Type text into input fields, textareas, or any editable element with human-like typing simulation.

Parameters:

• url (required): URL of the page
• selector (required): CSS selector for the input element
• text (required): Text to type
• clear (optional): Clear existing text first (default: true)
• delay (optional): Delay between keystrokes in ms (default: 50)
• timeout (optional): Maximum wait time in milliseconds (default: 30000)

Example:

{ 
  url: "https://example.com", 
  selector: "#username", 
  text: "myuser@example.com" 
}

3. get_interactive_elements - List all interactive elements

Discover all clickable and interactive elements on the page - links, buttons, inputs, elements with onclick handlers.

Parameters:

• url (required): URL of the page
• limit (optional): Maximum number of elements to return (default: 50)

Returns: Array of elements with details (tag, text, selector, href, type, id, hasOnClick, role)

Example:

{ url: "https://example.com", limit: 20 }

4. wait_for_element - Wait for element to appear

Wait for an element to appear on the page (useful after clicking something that triggers dynamic content).

Parameters:

• url (required): URL of the page
• selector (optional): CSS selector to wait for
• text (optional): Text content to wait for if selector not provided
• timeout (optional): Maximum wait time in milliseconds (default: 30000)

Example:

{ url: "https://example.com", selector: ".success-message" }

5. get_current_html - Get updated HTML without reloading (NEW! 🚀)

Efficiently get the current HTML state from an already-loaded page without navigation or reloading. Use this after interactions (click_element, type_text, wait_for_element) to get the updated DOM state.

Why use this instead of fetch_webpage?

• ⚡ Much faster - no page reload, just extracts current DOM
• 🎯 More accurate - captures exact state after interaction
• 💾 Preserves state - doesn't lose dynamic JavaScript state
• 🔄 Efficient - perfect for interactive workflows

Parameters:

• url (required): URL of the page (must be already loaded via fetch_webpage)
• removeUnnecessaryHTML (optional): Clean HTML for size reduction (default: true, ~90% smaller)

Example:

{ url: "https://example.com", removeUnnecessaryHTML: true }

Performance comparison:

fetch_webpage after interaction:  2-5 seconds (reloads page)
get_current_html after interaction: 0.1-0.3 seconds (just extracts HTML) ✅

Usage Workflow

Efficient interactive workflow (NEW!):

1. First, fetch the page:

   fetch_webpage({ url: "https://example.com/login" })

2. Discover interactive elements:

   get_interactive_elements({ url: "https://example.com/login" })

3. Fill in the form:

   type_text({ url: "https://example.com/login", selector: "#username", text: "user@example.com" })
   type_text({ url: "https://example.com/login", selector: "#password", text: "mypassword" })

4. Click the submit button:

   click_element({ url: "https://example.com/login", selector: "#submit" })
   // or by text: click_element({ url: "https://example.com/login", text: "Sign In" })

5. Wait for content to load:

   wait_for_element({ url: "https://example.com/dashboard", selector: ".dashboard-content" })

6. Get updated HTML efficiently (no reload!):

   get_current_html({ url: "https://example.com/dashboard" })
   // ✅ Fast! Just extracts current DOM without reloading the page

When to use get_current_html vs fetch_webpage:

• Use fetch_webpage: Initial page load, navigation to new URLs, auth flows
• Use get_current_html: After clicks, form fills, waits - when page is already loaded ✅

Key Features

• ✅ Works with any clickable element - not just <a> tags (buttons, divs with onclick, etc.)
• ✅ Text-based selection - click elements by their visible text
• ✅ Human-like typing - simulates natural keystroke delays
• ✅ Automatic scrolling - scrolls elements into view before interaction
• ✅ Smart element detection - finds the most specific match when searching by text
• ✅ Session preservation - all interactions happen in the same browser tab

Auth-assisted fetch flow

• AI assistant 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

Optional environment variables for advanced configuration:

• CHROME_PATH: Custom path to Chrome/Edge executable
• CHROME_USER_DATA_DIR: Custom browser profile directory
• CHROME_REMOTE_DEBUG_HOST: DevTools host (default: 127.0.0.1)
• CHROME_REMOTE_DEBUG_PORT: DevTools port (default: 9222)
• CHROME_WS_ENDPOINT: Explicit WebSocket endpoint URL
• DEFAULT_FETCH_URL or MCP_DEFAULT_FETCH_URL: Default URL when called without params

Set these in your shell or system environment before running the MCP server.

Tips

• Universal auth: Works with ANY authenticated site - corporate intranets, SSO, OAuth, SAML, login pages, CAPTCHA, human verification, etc.
• No re-authentication needed: Automatically reuses the same tab for URLs on the same domain, keeping your auth session alive across multiple page fetches
• Automatic page loading: Tool waits for pages to fully load (default 60s timeout, waits for network idle). AI assistant 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 pages, verify Chrome/Edge instance is signed in and the site opens there.
• Use a dedicated profile directory to avoid interfering with your daily browser.
• For heavy pages, add waitForSelector to ensure post-login content appears before extraction.