Metadata-Version: 2.5
Name: gsearch-agent
Version: 0.1.0
Summary: Real Google Search for AI agents, over MCP: real URLs, AI Overview and People also ask as typed JSON.
Project-URL: Homepage, https://github.com/RayenMlayeh/gsearch
Project-URL: Source, https://github.com/RayenMlayeh/gsearch
Project-URL: Issues, https://github.com/RayenMlayeh/gsearch/issues
Author: Rayen Mlayeh
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agents,camoufox,google-search,llm,mcp,mcp-server,serp,web-search
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: camoufox[geoip]==0.5.6
Requires-Dist: curl-cffi<0.17,>=0.16
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pydantic<3,>=2.9
Requires-Dist: selectolax<2,>=1.0
Provides-Extra: dev
Requires-Dist: anyio; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Description-Content-Type: text/markdown

# gsearch

**Real Google Search for your AI agent. No API key. Self-hosted. Over MCP.**

<!-- mcp-name: io.github.RayenMlayeh/gsearch -->

Your agent calls `google_search` and gets Google's actual results page as typed JSON: every link resolved to
its real URL, plus the AI Overview, People also ask and related searches. A real Firefox
([Camoufox](https://github.com/daijro/camoufox)) runs Google's page as it is, on your own IP or through any
proxy you already have.

Screenshots, measured results and the full documentation: **https://github.com/RayenMlayeh/gsearch**

## Quick start

```bash
uv tool install gsearch-agent                         # or: pipx install gsearch-agent
gsearch setup                                         # downloads the browser once (~1 GB), prints your MCP config
claude mcp add gsearch --scope user -- gsearch-mcp    # or any MCP client
```

Without a proxy, gsearch uses your own IP, at most 20 searches an hour. For more, add a proxy in any format
(rotating or static; HTTP, HTTPS or SOCKS5) with a hard data limit:

```bash
claude mcp add gsearch --scope user -e GSEARCH_PROXY="gate.example.com:7000:user-sid-{sid}:password" -e GSEARCH_DATA_LIMIT_MB=1000 -- gsearch-mcp
```

## What your agent gets

| MCP tool | Returns |
|---|---|
| `google_search(query, page, lang, country, time_range, site)` | Organic results with real URLs, AI Overview, People also ask, related searches, ads, pagination. A block is an error with `retry_after_s`, never an empty list. |
| `google_search_status()` | Proxy data used against the limit, IPs used and blocked, the cache. Never contacts Google. |

Every string is flagged as untrusted third-party text (`meta.untrusted_content`), because search results can
carry prompt injection.

The same search is available as a CLI (`gsearch search "query"`) and from Python (`gsearch_core.client.SearchClient`).

## Legal

Automated access to Google Search may breach Google's Terms of Service. gsearch ships no CAPTCHA solver and
never forges Google's tokens. Read the
[legal and responsible-use section](https://github.com/RayenMlayeh/gsearch#-legal-and-responsible-use) before
running live searches.

MIT licensed. Camoufox (MPL-2.0) is installed from PyPI as a dependency and is never vendored.
