Serper Search Proxy for OpenWebUI

A proxy that connects Open WebUI to the Serper Google Search and scrape APIs. One container provides three integrations:

• Web search (POST /search) - Open WebUI external web search engine
• Web loader (POST /loader) - Open WebUI external web loader, backed by the Serper scrape API
• MCP server (/mcp) - Streamable HTTP endpoint with two tools, google_search and google_fetch_webpage, so the model can search and read pages during a conversation

Open WebUI has a native Serper search integration. This proxy is for setups that also want the Serper scrape API as the web loader and as an MCP fetch tool, through one container and one API key. It also fits network-isolated deployments where Open WebUI cannot reach Serper directly: the proxy runs on a host with internet egress and Open WebUI only needs a route to the proxy.

How it works

No credentials are stored on the server. Every request to /search, /loader, and the MCP tools must carry Authorization: Bearer <your Serper API key>. The key is forwarded to Serper as the X-API-KEY header. If Serper rejects it, /search and /loader respond with the same 401 or 403 status, and the MCP tools return a tool error carrying that status.

Search responses are normalized into the [{link, title, snippet}] format Open WebUI expects: results from answerBox, knowledgeGraph, organic, and news are merged, deduplicated by link, and capped at the requested count. /loader returns [{page_content, metadata}], with source and title in the metadata.

Endpoints

Method	Path	Purpose	Auth
GET	/	Service name and version	none
GET	/health	Health check	none
POST	/search	Open WebUI external web search	bearer (Serper API key)
POST	/loader	Open WebUI external web loader	bearer (Serper API key)
POST/GET	/mcp	MCP Streamable HTTP endpoint	bearer (Serper API key)

Quick start

From Docker Hub:

docker run -d --name serper-proxy -p 8000:8000 edgaras0x4e/serper-proxy

Or build from source:

docker build -t serper-proxy .
docker run -d --name serper-proxy -p 8000:8000 serper-proxy

Minimal docker-compose.yml:

services:
  serper-proxy:
    image: edgaras0x4e/serper-proxy
    ports:
      - "8000:8000"

Verify:

curl http://localhost:8000/health

Configuration

All configuration is via environment variables. None are required.

Variable	Default	Description
SERPER_ENDPOINT	https://google.serper.dev/search	Serper search API URL
SERPER_SCRAPE_ENDPOINT	https://scrape.serper.dev	Serper scrape API URL
SERPER_TIMEOUT	20	Timeout in seconds for requests to Serper
SERPER_DEFAULT_COUNT	10	Number of search results when the request does not specify one
SERPER_GL	unset	Country code sent to Serper as gl (for example us)
SERPER_HL	unset	Interface language sent to Serper as hl (for example en)
MCP_ALLOWED_HOSTS	serper-proxy:*,localhost:*,127.0.0.1:*	Comma-separated Host values accepted by /mcp (DNS-rebinding protection). Must include every hostname clients use to reach /mcp.
SERPER_SEARCH_TOOL_DESCRIPTION	see below	Description advertised for the google_search MCP tool
SERPER_FETCH_TOOL_DESCRIPTION	see below	Description advertised for the google_fetch_webpage MCP tool

The two description variables set what the model reads when it decides which tool to call. The defaults name this server as the primary search and page fetch tool, which matters when another search MCP server is connected alongside it: without that, a model picks between similar tools arbitrarily. Override them to change the wording without rebuilding the image.

Connecting to Open WebUI

The URLs must be reachable from the Open WebUI container: serper-proxy:8000 works on a shared Docker network, otherwise use a routable hostname.

Web search

Admin Panel > Settings > Web Search, in the Search section:

1. Turn on Web Search
2. Set Web Search Engine to external
3. Set External Web Search URL to http://serper-proxy:8000/search
4. Set External Web Search API Key to your Serper API key
5. Click Save

Web loader

Same tab, in the Loader section:

1. Set Web Loader Engine to external
2. Set External Web Loader URL to http://serper-proxy:8000/loader
3. Set External Web Loader API Key to your Serper API key
4. Click Save

MCP tools

Admin Panel > Settings > Integrations, in the Tools section (External Tool Servers), click Add Connection:

1. Set Type to MCP (Streamable HTTP)
2. Set URL to http://serper-proxy:8000/mcp
3. Fill in ID, which is required for MCP connections, for example serper
4. Set Auth to Bearer and enter your Serper API key as the API Key
5. Click Save

If Open WebUI reaches the proxy at some other hostname, add it to MCP_ALLOWED_HOSTS, otherwise /mcp returns 421.

MCP tools

Tool	Arguments	Returns
google_search	query, count (1-100, default SERPER_DEFAULT_COUNT)	list of {link, title, snippet}
google_fetch_webpage	url, start_index (default 0), max_length (max 40000)	{url, title, text, start_index, total_chars, truncated}

google_fetch_webpage pages through long documents: call it again with start_index advanced by max_length while truncated is true.

Testing the endpoints

curl -X POST http://localhost:8000/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your Serper API key>" \
  -d '{"query": "open webui external search", "count": 5}'

curl -X POST http://localhost:8000/loader \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your Serper API key>" \
  -d '{"urls": ["https://example.com/article"]}'

Behavior notes

• /loader accepts up to 20 URLs per request. A URL that fails to scrape is skipped and logged so the rest of the batch still loads; 401/403 aborts the batch because every URL would fail the same way. Pages that return no text are skipped.
• Each /loader URL and each google_fetch_webpage call is one request to the Serper scrape API.

Local development

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --host 0.0.0.0 --port 8000

License

MIT