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
| Need | Browser Search MCP | |------|--------------------| | No search API key | Uses your browser by default | | Real web pages | Reads and cleans top result pages | | Vague user questions | Expands natural-language intent into search queries | | Quality control | Marks results as strict or partial and reports missing anchors | | Private/local workflows | Runs as an MCP server on your machine | | Logged-in browser context | Can integrate with browser-takeover bridge |
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..."
}
}
]
}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 9090Then 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-mcpLive 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
| Feature | Status | Description | |---------|--------|-------------| | Google, Bing, Baidu, DuckDuckGo | Yes | DOM + JS extraction | | Persistent browser session | Yes | Reuses CDP connection | | Result caching | Yes | LRU with configurable TTL | | Config file | Yes | JSON + env vars | | Auto-reconnect | Yes | Transparent reconnection | | browser-takeover bridge | Yes | Auto-detected extension bridge | | CAPTCHA detection | Yes | Auto fallback on CAPTCHA | | Engine fallback | Yes | Automatic on failure/CAPTCHA | | Deep mode | Yes | Auto-extracts top 2 result content | | Pagination | Yes | Multi-page search support | | Time filters | Yes | hour/day/week/month/year | | Intent planning | Yes | Platform/topic/task extraction plus query expansion | | Engine health check | Yes | Tracks per-engine availability | | Cross-engine dedup | Yes | Deduplicate multi-engine results | | API providers (Tavily/Brave) | Yes | Faster, API-key based | | HTTP API | Yes | FastAPI + OpenAI compatible | | Codex plugin | Yes | Auto-install as Codex plugin | | Fallback parsers | Yes | Text-based when JS fails | | Retry on failure | Yes | Exponential backoff |
MCP Tools
| Tool | Description | |------|-------------| | web_search_plan | Analyze intent and candidate queries without launching a browser | | web_search | Search a single engine, returns JSON results | | web_search_multi | Search multiple engines simultaneously | | web_search_read_page | Read structured page content for a URL | | web_research | Search and read top result pages for citation-ready research | | web_search_status | Check browser, bridge, and cache status | | web_search_discover_browsers | Find CDP-enabled browsers |
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
| Variable | Example | Description | |----------|---------|-------------| | BROWSER_SEARCH_HEADLESS | true | Run browser headless | | BROWSER_SEARCH_PROVIDER | tavily | Choose provider: browser/tavily/brave | | BROWSER_SEARCH_TAVILY_KEY | tvly-xxx | Tavily API key | | BROWSER_SEARCH_BRAVE_KEY | ... | Brave Search API key | | BROWSER_SEARCH_CACHE_TTL | 300 | Cache TTL in seconds | | BROWSER_SEARCH_DEFAULT_ENGINE | bing | Default search engine | | BROWSER_SEARCH_BROWSER | edge | Browser executable name | | BROWSER_SEARCH_PORT | 9333 | CDP remote debugging port | | BROWSER_SEARCH_USER_DATA_DIR | /tmp/browser-search-profile | Browser profile directory | | BROWSER_SEARCH_BROWSER_PATH | /path/to/browser | Explicit browser executable path |
How It Works
LLM/Agent -> MCP Client -> browser-search-mcp -> Browser (CDP) -> Search Engine
| (optional)
browser-takeover extension- MCP server finds or launches a Chrome/Edge browser with remote debugging
- Navigates to the search engine
- Extracts structured results via JavaScript DOM parsing
- Returns title, url, snippet as JSON
- 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.mdRequirements
- 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:#fffSupport
If this project helps you, optional support is welcome:
Bug reports and contributions are welcome. See CONTRIBUTING.md and SUPPORT.md.
