# Google MCP Server

Model Context Protocol (MCP) server that exposes **Google** search as a tool for LLM clients (Claude Desktop, Cursor, VS Code, ...), backed by a self-hosted [SearXNG](https://github.com/searxng/searxng) metasearch instance.

SearXNG aggregates results from Google, DuckDuckGo, Brave, Wikipedia, and more with its own request handling — no browser fingerprinting, no API keys, fully self-hosted.

Part of the MCP Search Servers project:

| Repo | What it is |
|------|------------|
| [duckduckgo-mcp](https://git.jarianc.com/jarianc/duckduckgo-mcp) | Same design for DuckDuckGo search |

## Service

| Service     | Port | MCP tool       | Description                    |
|-------------|------|----------------|--------------------------------|
| `google-mcp`| 3001 | `google_search`| Google results via SearXNG     |
| `searxng`   | —    | —              | Internal metasearch engine (not published) |

The server exposes:

- `/sse` + `/messages/` — MCP SSE transport
- `/search?q=...&num=N` — plain HTTP JSON endpoint
- `/health` — liveness probe

## Quick Start

```bash
cp .env.example .env        # fill in SEARXNG_SECRET
docker compose up -d --build
```

Generate a SearXNG secret:

```bash
python3 -c "import secrets; print(secrets.token_hex(32))"
```

Verify:

```bash
curl http://localhost:3001/health
curl "http://localhost:3001/search?q=python&num=3"
```

Then point your LLM client at `http://localhost:3001/sse`. Client configuration examples for Claude Desktop, Cursor/Windsurf, and VS Code are in [USAGE.md](USAGE.md).

## Tool Contract

```json
{
  "name": "google_search",
  "arguments": { "query": "Python programming language", "num_results": 5 }
}
```

Returns numbered results with title, URL, and snippet (max 20 results, queries capped at 500 characters).

## Architecture

```
LLM client (Claude Desktop, Cursor, ...)
        |  MCP / SSE
        v
+---------------+      +----------------+
|   google-mcp  | ---- |      SearXNG   | --> Google, Brave, Wikipedia, ...
|   (:3001)     |      |  (internal)    |
+---------------+      +----------------+
```

## Project Structure

```
.
├── google-mcp/        # MCP server (SSE transport + tools)
│   ├── server.py
│   └── Dockerfile
├── lib/               # Shared search engine implementations
│   ├── google_search.py
│   ├── duckduckgo_search.py  # also used by the duckduckgo-mcp sibling repo
│   ├── playwright_manager.py
│   └── rate_limiter.py
├── tests/             # Unit tests (rate limiter, result parsing)
├── integration_test.py
├── test_client.py
├── searxng-settings.yml
└── docker-compose.yml
```