Browser Search MCP

Real browser search for AI agents. Browser Search MCP lets Claude Desktop, Cursor, Codex, Ollama, and other MCP clients search the web through Chrome/Edge, read result pages, expand vague user questions, and report whether the results actually match the user's intent.

Search like a real browser. Read like a research agent.

基于真实浏览器的 MCP 搜索引擎服务器 - 让任何支持 MCP 的大模型都能搜索网页内容。 Browser Search MCP - Web search via real browser for any LLM.

Built on the same CDP extension bridge architecture as browser-takeover-bridge.

Launch Week

If you are discovering this project from a post, start here:

• Install in 30 seconds: pip install browser-search-mcp

• Best default tool: web_research

• Preview query expansion: web_search_plan

• Use cases: local agents, private research assistants, authenticated browser search, citation-ready page reading

• Launch assets: Launch Week Plan and Ready-to-post copy

Why agents use it

Example: plan before searching

{
  "query": "home projector vs TV which is better",
  "intent": {
    "topic": ["projector", "TV"],
    "task": ["compare", "buying guide", "recommendation"]
  },
  "candidate_queries": [
    "home projector vs TV which is better",
    "projector TV comparison pros cons buying guide",
    "projector TV comparison recommendation"
  ]
}

Example: research-ready result

{
  "ok": true,
  "query": "2026 exam English study plan",
  "quality": "strict",
  "diagnostics": {
    "missing_anchor_groups": []
  },
  "results": [
    {
      "title": "Example result",
      "url": "https://example.com",
      "page": {
        "ok": true,
        "content": "Cleaned page text for the agent..."
      }
    }
  ]
}

Related MCP server: Google Search Tool

Why?

Local LLMs (Ollama, etc.) cant search the web. HTTP-based search tools get blocked by anti-bot measures. This project uses a real browser to search - no API keys, no blocking, no fake results.

Quick Start

pip install browser-search-mcp

# Start the MCP server
browser-search-mcp

# Optional CLI helpers
browser-search-mcp --help
browser-search-mcp status
browser-search-mcp doctor
browser-search-mcp http 9090

Then configure in any MCP client:

{
  "mcpServers": {
    "browser-search": {
      "command": "browser-search-mcp"
    }
  }
}

Bridge Integration (browser-takeover extension)

When installed alongside the browser-takeover-bridge extension, browser-search-mcp automatically detects the extension and routes searches through it instead of launching a headless CDP browser.

Why use the bridge?

• Authenticated sessions - search while logged into services (e.g., intranet, social media, internal tools)

• Faster startup - no need to launch a new browser; reuses the extension's existing connection

• Lower resource usage - share one browser session instead of spawning a separate headless instance

How it works:

LLM/Agent -> MCP Client -> browser-search-mcp -> bridge (extension) -> user's browser -> search engine

The bridge check runs automatically at startup. If the extension is not detected, the server falls back to the standard CDP path (launching its own browser). No configuration needed.

Detection: Run web_search_status to see if the bridge is active: json { "bridge": { "available": true, "search_available": true } }

Quick Demo

Search the web in seconds from any MCP-compatible LLM:

pip install browser-search-mcp
browser-search-mcp

Live search result (Bing, ~5s):

[
  {
    "title": "What is the Model Context Protocol (MCP)?",
    "url": "https://modelcontextprotocol.io/",
    "snippet": "MCP is an open standard for connecting AI applications to external systems."
  },
  {
    "title": "MCP Server Guide",
    "url": "https://example.com/mcp-guide",
    "snippet": "Complete guide to setting up MCP servers for web search."
  },
  {
    "title": "Browser Search MCP",
    "url": "https://github.com/fangsylar-pixel/browser-search",
    "snippet": "Open source MCP server using real browser for web search."
  }
]

No API keys required. No blocking. Just a real browser doing real searches.

Features

MCP Tools

web_search_plan is useful before an expensive search: it returns parsed intent, required coverage anchors, and expanded candidate queries for broad customer requests such as creator topics, product comparisons, tutorials, trends, and recommendations.

web_research is the best default for agents that need grounded answers. It rewrites natural-language questions into search queries, retries across engines, filters off-topic results, and labels result quality as strict or partial based on whether the platform/topic/task anchors were covered. It also returns diagnostics, cleaned page content for the top results, title, final URL, description, detected publish time, and truncation metadata.

Configuration

Config file: ~/.browser-search-mcp/config.json

Browser Mode (default)

{
  "browser": {
    "name": "edge",
    "headless": false,
    "port": 9222
  },
  "cache": {
    "enabled": true,
    "ttl": 300
  }
}

API Mode (faster, needs API key)

{
  "provider": {
    "name": "tavily",
    "tavily_api_key": "tvly-your-key-here"
  }
}

Environment Variables

How It Works

LLM/Agent -> MCP Client -> browser-search-mcp -> Browser (CDP) -> Search Engine
                                                    | (optional)
                                          browser-takeover extension

1. MCP server finds or launches a Chrome/Edge browser with remote debugging

2. Navigates to the search engine

3. Extracts structured results via JavaScript DOM parsing

4. Returns title, url, snippet as JSON

5. Results cached for 5 minutes by default

Project Structure

browser-search-mcp/
  browser_search_mcp/
    config.py    Configuration via JSON file + env vars
    cdp.py       CDP browser control with persistent sessions
    bridge.py    Browser-takeover extension bridge client
    search.py    Search orchestration with caching and retry
    parsers.py   Text-based search result parsers (fallback)
    bridge_provider.py  Bridge-based search provider (optional, auto-detected)
    providers.py API search providers (Tavily, Brave)
    server.py    FastMCP server with 5 search tools
    http_api.py  HTTP API server (FastAPI + OpenAI-compatible endpoint)
    setup_assistant.py  Prerequisites check
  .codex-plugin/ Codex plugin packaging
  .github/      CI and issue templates
  website/      Promotional website (GitHub Pages)
  README.md, CONTRIBUTING.md, LICENSE, SUPPORT.md

Requirements

• Python 3.11+

• Chrome or Edge installed

• Optional: browser-takeover-bridge extension (for authenticated sessions)

License

MIT

Architecture

flowchart TB
    subgraph User[User Environment]
        LLM[LLM / Agent]
        MCP[MCP Client]
    end
    subgraph Browser[Browser Layer]
        BRIDGE[Bridge Extension]
        CDP[Chrome/Edge CDP]
    end
    subgraph Search[Search Layer]
        BSM[browser-search-mcp]
        API_PROV[API Providers]
    end
    subgraph Engines[Search Engines]
        G[Google]
        B[Bing]
        BA[Baidu]
        D[DuckDuckGo]
    end

    LLM --> MCP --> BSM
    BSM -->|Priority 1| BRIDGE --> CDP --> Engines
    BSM -->|Priority 2| API_PROV --> Engines
    BSM -->|Priority 3| CDP --> Engines

    style BSM fill:#10b981,color:#fff
    style BRIDGE fill:#6366f1,color:#fff
    style API_PROV fill:#f59e0b,color:#fff

Support

If this project helps you, optional support is welcome:

Support on Afdian

Bug reports and contributions are welcome. See CONTRIBUTING.md and SUPPORT.md.