Web Search

You can run a self-contained MCP server that provides Google Custom Search, web content viewing, and advanced bot-detection avoidance. It handles search queries, fetches and renders web pages, and manages browser instances efficiently, so you can build interactive search tools into your MCP client with strong performance and security controls.

How to use

You use this server with your MCP client to perform fast Google searches and to view web pages. The server exposes two main tools you can call from your MCP client: a search tool that accepts a query and optional filters, and a view URL tool that returns the contents of a given URL with optional media inclusion and formatting. You configure the client to connect to the local MCP server, then issue requests to perform searches or render pages as part of your workflows.

How to install

Prerequisites: you need Bun runtime v1.0 or higher and Google API credentials (an APIKey and a Search Engine ID).

Step 1: Install dependencies and build the server locally.

# Install dependencies
bun install

# Build the TypeScript files
bun run build

Configuration and runtime details

Cookie setup for authenticated site access: you can export cookies locally and point the server at them via an environment variable.

Set the BROWSER_COOKIES_PATH environment variable to the absolute path of your cookies file.

MCP Server configuration is provided as a JSON snippet. This example defines a local stdio-based server using Bun to run the built MCP index, with environment variables for API credentials, rate limits, cache settings, and browser options.

{
  "mcpServers": {
    "web-search": {
      "command": "bun",
      "args": [
        "run",
        "/ABSOLUTE/PATH/TO/web_search_mcp/dist/index.js"
      ],
      "env": {
        "GOOGLE_API_KEY": "your_api_key",
        "GOOGLE_SEARCH_ENGINE_ID": "your_search_engine_id",
        "MAX_CONCURRENT_BROWSERS": "3",
        "BROWSER_TIMEOUT": "30000",
        "RATE_LIMIT_WINDOW": "60000",
        "RATE_LIMIT_MAX_REQUESTS": "60",
        "SEARCH_CACHE_TTL": "3600",
        "VIEW_URL_CACHE_TTL": "7200",
        "MAX_CACHE_ITEMS": "1000",
        "BROWSER_POOL_MIN": "1",
        "BROWSER_POOL_MAX": "5",
        "BROWSER_POOL_IDLE_TIMEOUT": "30000",
        "REBROWSER_PATCHES_RUNTIME_FIX_MODE": "addBinding",
        "REBROWSER_PATCHES_SOURCE_URL": "jquery.min.js",
        "REBROWSER_PATCHES_UTILITY_WORLD_NAME": "util",
        "REBROWSER_PATCHES_DEBUG": "0",
        "BROWSER_COOKIES_PATH": "C:\\path\\to\\cookies.json",
        "LOG_LEVEL": "info",
        "NO_COLOR": "0",
        "BUN_FORCE_COLOR": "1",
        "FORCE_COLOR": "1"
      }
    }
  }
}

Logging

You control logging with these environment variables. You can reduce noise or enable verbose output for debugging.

LOG_LEVEL=info
NO_COLOR=0
BUN_FORCE_COLOR=1
FORCE_COLOR=1

Bot detection avoidance

The server uses a browser automation layer designed to minimize bot-detection signals. It applies runtime binding tricks, masks script URLs, uses a generic utility world name, and configures the browser with careful startup arguments to reduce automation indicators.

Using with Claude Desktop

If you use Claude Desktop, ensure it is installed and up to date. Add the server configuration shown above to your Claude Desktop configuration, then restart Claude Desktop and verify the tools are available.

Troubleshooting

If you run into integration issues, check logs and verify configuration paths are absolute. Common problems include the server not appearing, tool calls failing, or path mismatches. Ensure you restarted Claude Desktop after changes.

Development

Development commands shown here help you test and lint the server during iteration.

# Run in development mode with watch
bun --watch run dev

# Run tests
bun run test

# Run linter
bun run lint

Important notes

Bot detection: while the avoidance features reduce common detection methods, some sites may still detect automation through other means. Use appropriate proxies and user-agent configurations as needed.

Performance: browsers are pooled and reused, idle instances are cleaned up, and resource limits help prevent overloading.

License

MIT license applicable to this MCP server.

Available tools

search

Performs a Google Custom Search with configurable query, trustedDomains, excludedDomains, resultCount, safeSearch, and dateRestrict.

view_url

Renders a target URL with optional content controls such as images, videos, link preservation, and code formatting.