edgaras0x4e/serper-proxy repository overview

⁠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

⁠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.

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

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