---
name: gsearch-mcp
description: >-
  Google Search CLI and MCP server for AI agents. Search Google (regular + AI Mode)
  and fetch/parse web pages to Markdown. Supports search type filtering (news, images,
  videos, shopping, books, forums, short_videos) and time-filtered searches (last hour,
  12h, day, week, month, year, or custom date range). Use when the user asks to
  search Google, search the web, look something up, find recent news, find information
  online, or fetch a web page.
version: "0.0.3"
---

# Google Search MCP

Search Google and fetch web pages for AI agents.

## Quick Reference

Run `gsearch --ai` for comprehensive AI-optimized documentation.

```bash
gsearch --ai                # Full AI reference (RECOMMENDED)
gsearch --help              # CLI help
gsearch doctor              # Diagnose setup
```

## Critical Rules

1. **First run**: `gsearch setup` runs automatically on first search (~8s warmup)
2. **Rate limited**: 1 search per 2 seconds by default
3. **No auth needed**: Anonymous, pseudonymous sessions
4. **SSRF protection**: `gsearch fetch` validates URLs against private IP ranges
5. **ALWAYS use time filters** when searching for news, recent events, or time-sensitive information

## Time Filtering (IMPORTANT)

When the user asks for recent information, news, or anything time-sensitive, you MUST use time filters. Default search returns results of any age.

### Quick Time Filters

| Filter | CLI Flag | MCP Parameter | Use When |
|--------|----------|---------------|----------|
| Last hour | `--time hour` or `--time 1h` | `time_filter="hour"` | Breaking news, live events |
| Last 12 hours | `--time 12h` | `time_filter="12h"` | Today's news |
| Last 24 hours | `--time day` or `--time 24h` | `time_filter="day"` | Yesterday's news |
| Last week | `--time week` or `--time 7d` | `time_filter="week"` | This week's developments |
| Last month | `--time month` | `time_filter="month"` | Recent developments |
| Last year | `--time year` | `time_filter="year"` | Within the past year |
| Last N hours | `--time Nh` (e.g., `6h`) | `time_filter="6h"` | Custom hour window |

### Custom Date Range

For specific date ranges, use `--after` and `--before` with YYYY-MM-DD format:

```bash
gsearch "quarterly earnings" --after 2026-01-01 --before 2026-03-31
```

MCP equivalent:
```
gsearch_search(query="quarterly earnings", date_from="2026-01-01", date_to="2026-03-31")
```

### When to Use Which Filter

- "latest news about X" -> `time_filter="day"` or `time_filter="12h"`
- "what happened today with X" -> `time_filter="day"`
- "breaking news X" -> `time_filter="hour"`
- "recent developments in X" -> `time_filter="week"`
- "X news this month" -> `time_filter="month"`
- "X in 2026" -> `time_filter="year"` or use date range
- "X between January and March" -> `date_from="2026-01-01"`, `date_to="2026-03-31"`

## Search Types

Filter results by content type using `--type`:

| Type | CLI Flag | MCP Parameter | Returns |
|------|----------|---------------|---------|
| All (default) | `--type all` | `search_type="all"` | Regular search results |
| News | `--type news` | `search_type="news"` | News articles only |
| Images | `--type images` | `search_type="images"` | Image results |
| Videos | `--type videos` | `search_type="videos"` | Video results |
| Shopping | `--type shopping` | `search_type="shopping"` | Product listings |
| Books | `--type books` | `search_type="books"` | Book results |
| Forums | `--type forums` | `search_type="forums"` | Reddit, forums, Q&A |
| Short Videos | `--type short_videos` | `search_type="short_videos"` | TikTok, Shorts, Reels |

### Combining Type + Time Filters

The most powerful queries combine both:

```bash
gsearch "AI developments" --type news --time day       # news from last 24h
gsearch "kubernetes error" --type forums --time week   # forum posts this week
gsearch "best laptop 2026" --type shopping
gsearch "python tutorial" --type videos
```

MCP equivalent:
```
gsearch_search(query="AI news", search_type="news", time_filter="day")
```

### When to Use Which Type
- "latest news about X" -> search_type="news", time_filter="day"
- "find discussions about X" -> search_type="forums"
- "buy X" or "price of X" -> search_type="shopping"
- "how to X" (video) -> search_type="videos"
- "X review" (recent) -> search_type="news", time_filter="week"

## Workflow Decision Tree

```
User wants to...
|
+-- Search for recent news or time-sensitive info
|   +-- gsearch "AI news" --time day            # last 24h
|   +-- gsearch "breaking news" --time 1h       # last hour
|   +-- gsearch "weekly recap" --time week       # last 7 days
|   +-- gsearch "Q1 earnings" --after 2026-01-01 --before 2026-03-31
|
+-- Search a specific content type
|   +-- gsearch "AI developments" --type news    # news articles only
|   +-- gsearch "python tutorial" --type videos  # video results
|   +-- gsearch "k8s error" --type forums        # Reddit, forums, Q&A
|   +-- gsearch "best laptop" --type shopping    # product listings
|   +-- gsearch "react hooks" --type short_videos # TikTok, Shorts, Reels
|   +-- gsearch "machine learning" --type books  # book results
|   +-- gsearch "cat" --type images              # image results
|
+-- Combine type + time filter
|   +-- gsearch "AI news" --type news --time day # news from last 24h
|   +-- gsearch "k8s error" --type forums --time week
|
+-- Search the web (any time)
|   +-- gsearch "query"                          # default search
|   +-- gsearch search "query" --json            # JSON output
|   +-- gsearch search "query" --no-ai           # skip AI Overview
|
+-- Get AI-synthesized answer (like g.ai)
|   +-- gsearch ai "query"                       # all time
|   +-- gsearch ai "query" --time week           # with time filter
|   +-- gsearch ai "query" --json
|
+-- Fetch and read a web page
|   +-- gsearch fetch "url"                      # Markdown output
|   +-- gsearch fetch "url" --raw                # plain text
|   +-- gsearch fetch "url" --browser always     # JS-heavy sites
|
+-- First-time setup
|   +-- gsearch setup                            # warmup profile
|   +-- gsearch setup add cursor                 # configure MCP for Cursor
|   +-- gsearch doctor                           # diagnose issues
|
+-- Configure
    +-- gsearch config show
    +-- gsearch config set browser brave
```

## CLI Commands

### Search (default command)
```bash
gsearch "what is kubernetes"                     # regular search
gsearch "AI news" --time day                     # last 24 hours
gsearch "breaking: earthquake" --time 1h         # last hour
gsearch "market update" --time 12h               # last 12 hours
gsearch "releases" --after 2026-01-01 --before 2026-03-31
gsearch search "query" --json                    # JSON output
gsearch search "query" --no-ai                   # skip AI Overview
gsearch search "query" -n 5 --lang fr            # 5 results, French
```

### AI Mode
```bash
gsearch ai "explain kubernetes architecture"
gsearch ai "latest AI breakthroughs" --time week
gsearch ai "compare React vs Vue" --json
```

### Fetch URL to Markdown
```bash
gsearch fetch "https://kubernetes.io/docs/"
gsearch fetch "url" --raw                        # plain text
gsearch fetch "url" --browser always             # force browser for JS sites
```

### MCP Setup
```bash
gsearch setup add cursor                         # configure for Cursor
gsearch setup add claude-code                    # configure for Claude Code
gsearch setup add json                           # print JSON config snippet
gsearch setup list                               # show all supported tools
```

### Skill Install
```bash
gsearch skill install cursor                     # install for Cursor
gsearch skill install cc-claw                    # install for CC-Claw
gsearch skill list                               # show all targets
```

## MCP Tools

### gsearch_search

Google Search with AI Overview + organic results.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| query | str | (required) | Search query |
| max_results | int | 10 | Max organic results |
| include_ai | bool | True | Include AI Overview |
| language | str | "en" | Search language |
| region | str | None | Search region (US, CA, GB, etc.) |
| **search_type** | **str** | **None** | **"all", "news", "images", "videos", "shopping", "books", "forums", "short_videos"** |
| **time_filter** | **str** | **None** | **"hour", "12h", "day", "week", "month", "year", or "Nh"** |
| **date_from** | **str** | **None** | **Custom range start: "YYYY-MM-DD"** |
| **date_to** | **str** | **None** | **Custom range end: "YYYY-MM-DD"** |
| timeout_seconds | int | 30 | Operation timeout |

### gsearch_ai

Google AI Mode synthesized response with citations.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| query | str | (required) | Search query |
| language | str | "en" | Search language |
| **time_filter** | **str** | **None** | **"hour", "12h", "day", "week", "month", "year", or "Nh"** |
| **date_from** | **str** | **None** | **Custom range start: "YYYY-MM-DD"** |
| **date_to** | **str** | **None** | **Custom range end: "YYYY-MM-DD"** |
| timeout_seconds | int | 30 | Operation timeout |

### gsearch_fetch

Fetch URL and convert to clean Markdown.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| url | str | (required) | URL to fetch (https:// only) |
| format | str | "md" | "md", "text", or "raw_html" |
| use_browser | str | "auto" | "auto", "always", or "never" |
| timeout_seconds | int | 30 | Request timeout |

## Error Recovery

| Error | Solution |
|-------|----------|
| "unusual traffic" | Wait 30s, or: `gsearch setup --reset` |
| Browser not found | Install Chrome, Brave, or Edge |
| CDP connection failed | `gsearch doctor` to diagnose |
| Profile warmup failed | `gsearch setup --reset` |
| SSRF blocked | Only https:// public URLs allowed |
