AgentWebSearch-MCP

Local WebSearch without API keys + MCP Server

Need WebSearch for your local LLM (Ollama, LM Studio) or Claude Code? No API keys needed - just Chrome.

How It Works

This tool launches REAL Chrome browsers - not headless, not simulated.

It opens actual Chrome windows and controls them via CDP (Chrome DevTools Protocol). This is why it can bypass bot detection and CAPTCHA - because it IS a real browser.

┌─────────────────────────────────────────────────────────┐
│  Your Desktop                                           │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐       │
│  │ Chrome:9222 │ │ Chrome:9223 │ │ Chrome:9224 │       │
│  │   Naver     │ │   Google    │ │   Brave     │       │
│  │  (search)   │ │  (search)   │ │  (search)   │       │
│  └──────┬──────┘ └──────┬──────┘ └──────┬──────┘       │
│         │               │               │               │
│         └───────────────┼───────────────┘               │
│                         │ CDP (WebSocket)               │
│                    ┌────┴────┐                          │
│                    │   MCP   │                          │
│                    │ Server  │                          │
│                    └────┬────┘                          │
│                         │                               │
│                    Claude Code                          │
└─────────────────────────────────────────────────────────┘

Why real browsers?

• No API keys needed (you're just browsing)

• No rate limits (normal browser behavior)

• CAPTCHA resistant (real browser fingerprint)

• Login sessions persist (cookies saved)

• Korean portals work (Naver requires real browser)

Extensible to other sites

• Currently configured for search portals (Naver, Google, Brave)

• Can be extended to other sites by adding portal config

• Each site needs its own Chrome instance and session

Key Benefits

Features

• No API keys - Direct Chrome CDP (DevTools Protocol) control

• MCP Server - Use as Claude Code / Cursor / LM Studio tool

• AgentCPM-Explore - Search-optimized 4B model from OpenBMB/THUNLP (optional)

• Parallel search - 3 Chrome instances for Naver/Google/Brave simultaneously

• Bot detection bypass - Session persistence + stealth flags

• CAPTCHA resistant - Real browser sessions avoid most CAPTCHA challenges

Installation

1. Install dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Start Chrome (debugging mode)

python chrome_launcher.py start   # Start 3 Chrome instances
python chrome_launcher.py status  # Check status
python chrome_launcher.py stop    # Stop all

3. Login & Sync (optional but recommended)

By default, Chrome instances use temporary profiles (/tmp/). For persistent login:

1. Open CDP Chrome (after chrome_launcher.py start)

2. Sign in to Google in the Chrome window

3. Enable sync (Settings → Sync)

Benefits:

• OAuth login ("Sign in with Google") works automatically

• Saved passwords auto-fill

• Better search results (personalized)

• Sessions persist across restarts

Note: To make profiles permanent, change profile paths in chrome_launcher.py from /tmp/chrome-*-profile to ~/.config/chrome-cdp/*

MCP Server

Use web search as an MCP tool in Claude Code, Cursor, LM Studio, or OpenClaw/Moltbot.

Quick Start

# Start Chrome first
python chrome_launcher.py start

# Run MCP server (stdio mode)
python mcp_server.py

Claude Code Registration

claude mcp add agentwebsearch -s user -- python /path/to/mcp_server.py

Claude Code settings.json

{
  "mcpServers": {
    "agentwebsearch": {
      "command": "python",
      "args": ["/path/to/AgentWebSearch-MCP/mcp_server.py"],
      "env": {}
    }
  }
}

OpenClaw/Moltbot Registration

# Add MCP to OpenClaw
openclaw mcp add agentwebsearch -- python /path/to/mcp_server.py

# Or add to ~/.openclaw/config.json

SSE Mode (HTTP Server)

python mcp_server.py --sse --port 8902

Available MCP Tools

Tool Parameters

smart_search

agentcpm

Uses AgentCPM-Explore model (4B, OpenBMB/THUNLP) via SGLang to plan search queries, execute searches, and generate answers.

Requirements:

• SGLang server running on port 30001

• AgentCPM-Explore model loaded

First time setup: Model loading takes ~30-45 seconds. Use smart_search if you don't have SGLang set up.

get_search_status / cancel_search

Partial results support: When search takes too long, you can:

1. Call get_search_status to check progress and see results collected so far

2. Call cancel_search to stop the search and return partial results

Why AgentCPM-Explore? Trained specifically for search agent tasks by OpenBMB/THUNLP. Generates diverse queries and handles tool calling better than general-purpose models.

Example Usage

"Search latest AI news" → smart_search tool
"Deep search about GPT-5" → smart_search(depth="deep")
"Use AgentCPM for AI news" → agentcpm(query="AI news")

Standalone Agent (CLI)

Run search agent directly from command line.

# Default: SGLang backend
python search_agent.py "search query"

# Search depth
python search_agent.py "query" --depth simple   # snippets only (fast)
python search_agent.py "query" --depth medium   # fetch top 5 URLs (default)
python search_agent.py "query" --depth deep     # fetch all URLs (slow)

# Interactive mode
python search_agent.py -i

# CLI supports multiple backends (--llm ollama/lmstudio/openai)
python search_agent.py --list-backends

AgentCPM-Explore Setup (for agentcpm tool)

AgentCPM-Explore is a 4B parameter model from OpenBMB/THUNLP specifically trained for search agent tasks:

• Automatically generates diverse search queries (Korean/English, multiple perspectives)

• Optimized for tool calling (search, fetch_url)

• Based on Qwen3-4B-Thinking

# 1. Install SGLang (CUDA required)
pip install sglang[all]

# 2. Download AgentCPM-Explore model (~8GB)
# https://huggingface.co/openbmb/AgentCPM-Explore

# 3. Start server
MODEL_PATH=/path/to/AgentCPM-Explore ./start_sglang.sh

Note: The agentcpm MCP tool exclusively uses SGLang + AgentCPM-Explore. For other LLM backends, use smart_search or the CLI (search_agent.py --llm ollama).

Architecture

User Query
    |
MCP Server (mcp_server.py)
+-- web_search      → CDP Search only
+-- smart_search    → CDP Search + URL Fetch
+-- agentcpm        → SGLang + AgentCPM-Explore + CDP Search
    |
CDP Search (parallel)
+-- Chrome:9222 → Naver
+-- Chrome:9223 → Google
+-- Chrome:9224 → Brave
    |
Final Answer + Sources

File Structure

AgentWebSearch-MCP/
├── mcp_server.py         # MCP server (4 tools)
├── search_agent.py       # Standalone CLI agent
├── cdp_search.py         # CDP parallel search
├── chrome_launcher.py    # Chrome instance manager
├── llm_adapters/         # LLM adapters (CLI use)
│   ├── base.py           # Common interface
│   ├── sglang_adapter.py
│   ├── ollama_adapter.py
│   ├── lmstudio_adapter.py
│   └── openai_adapter.py
└── start_sglang.sh       # SGLang server startup

Performance

Requirements

• Python 3.10+

• Chrome/Chromium

• For agentcpm tool: SGLang + AgentCPM-Explore model

License

MIT License

Contributing

Portal addition PRs welcome! See PORTAL_CONFIG in cdp_search.py.

Co-Authored-By: inchul insung8150@users.noreply.github.com Co-Authored-By: Claude noreply@anthropic.com