gsearch-mcp-cli 0.0.1

Google Search CLI and MCP server for AI agents

gsearch-mcp-cli

Google Search CLI and MCP server for AI agents. Search Google (regular + AI Mode), fetch web pages as Markdown, with time filtering. No Google account needed.

Install

pip install gsearch-mcp-cli

Or with uv / pipx:

uv pip install gsearch-mcp-cli    # uv
pipx install gsearch-mcp-cli      # pipx (isolated)

Run without installing:

uvx --from gsearch-mcp-cli gsearch "your query"

Requirements: A Chromium-based browser (Chrome, Brave, Edge, Chromium, Vivaldi, or Opera).

Quick Start

gsearch setup                              # one-time profile warmup (~8s)
gsearch "what is kubernetes"               # search Google
gsearch "AI news" --time day               # last 24 hours
gsearch "breaking news" --time 1h          # last hour
gsearch ai "explain docker architecture"   # AI Mode (g.ai)
gsearch fetch "https://example.com"        # page to Markdown

Time Filtering

Filter results by time period -- critical for news and recent events:

gsearch "query" --time hour      # last hour
gsearch "query" --time 12h       # last 12 hours
gsearch "query" --time day       # last 24 hours
gsearch "query" --time week      # last 7 days
gsearch "query" --time month     # last month
gsearch "query" --time year      # last year
gsearch "query" --after 2026-01-01 --before 2026-03-31  # custom range

Commands

Command	Description
gsearch "query"	Google Search (default) with AI Overview + organic results
gsearch ai "query"	Google AI Mode -- synthesized answer with citations
gsearch fetch "url"	Fetch URL and convert to clean Markdown
gsearch setup	Browser profile warmup (one-time)
gsearch setup add <tool>	Configure MCP server for an AI tool
gsearch config show	Show configuration
gsearch doctor	Run diagnostics
gsearch skill install <tool>	Install skill for AI tools
gsearch --ai	Print AI-optimized documentation

MCP Server

For AI agents via Model Context Protocol:

gsearch-mcp                       # start MCP server (stdio)
gsearch setup add cursor          # configure for Cursor
gsearch setup add claude-code     # configure for Claude Code

MCP Tools:

• gsearch_search(query, time_filter="day", ...) -- Google Search
• gsearch_ai(query, time_filter="week", ...) -- AI Mode
• gsearch_fetch(url, format="md", ...) -- Fetch page as Markdown

How It Works

Uses headless Chrome via CDP (Chrome DevTools Protocol) with a persistent anonymous profile. Google's BotGuard requires a warmed-up browser session -- gsearch setup establishes this once. No Google account or login needed.

Supported AI Tools

MCP Setup (gsearch setup add): Claude Code, Gemini CLI, Cursor, Windsurf, Cline, Antigravity, Codex, OpenCode

Skill Install (gsearch skill install): Claude Code, Cursor, Codex, Gemini CLI, OpenCode, Antigravity, Cline, OpenClaw, CC-Claw

License

MIT