gsearch-mcp-cli 0.1.0

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.

Vibe Coding Alert

Full transparency: this project was built by a non-developer using AI coding assistants. If you're an experienced Python developer, you might look at this codebase and wince. That's okay.

The goal here was to learn — both about building CLI tools in Python and about how modern web applications work under the hood. The code works, but it's very much a learning project released solely for the purpose of research and education, not a polished product.

[!WARNING] Unofficial & Unsupported — This project is not affiliated with, endorsed by, or supported by Google. It interacts with Google Search and Google AI Mode through unofficial, undocumented methods that may break at any time without notice if Google changes their internal behavior, DOM structure, or bot detection. Use at your own risk. The author(s) accept no responsibility for any consequences, including but not limited to rate limiting or IP blocking. This project is released strictly for educational and research purposes only.

If you know better, teach us. PRs, issues, and architectural advice are all welcome. This is open source specifically because human expertise is irreplaceable.

Install

pip

pip install gsearch-mcp-cli

uv

uv tool install gsearch-mcp-cli

pipx

pipx install gsearch-mcp-cli

Run without installing (uvx)

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, Alef

License

MIT