openserp

OpenSERP

OpenSERP is a free self-hosted web search for AI agents and SEO. REST API and CLI for Google, Bing, Yandex, Baidu, DuckDuckGo and Ecosia.

No API keys, no per-search billing. It loads search results in browser and returns structured JSON with source engines and ranks. Read the linked pages as clean Markdown, or connect an agent through MCP.

Works with Claude Code, Cursor, Codex, Claude Desktop and any MCP client, Open WebUI (built-in provider), n8n, and plain HTTP from any language.

API examples · CLI · Agent setup · API reference

Quick Start

# Start the API server
docker run --rm --init -p 127.0.0.1:7000:7000 karust/openserp serve -a 0.0.0.0 -p 7000

# Search Google and read the top result as Markdown
curl "http://127.0.0.1:7000/google/search?text=how+do+mcp+servers+work&extract=1"

# Docker Compose
docker compose up

# Go
go install github.com/karust/openserp@latest
openserp serve

# From source
git clone https://github.com/karust/openserp.git
cd openserp && go build -o openserp . && ./openserp serve

Use with AI Agents

MCP: Claude Code, Codex, Cursor, Claude Desktop

Requires Node.js 18+ and a running OpenSERP server. Add the MCP server to your client:

claude mcp add openserp -- npx -y @openserp/mcp
codex mcp add openserp -- npx -y @openserp/mcp

Cursor (~/.cursor/mcp.json), Claude Desktop, Windsurf and other clients:

{
  "mcpServers": {
    "openserp": { "command": "npx", "args": ["-y", "@openserp/mcp"] }
  }
}

On native Windows, use cmd /c npx -y @openserp/mcp after -- in the CLI commands, or "command": "cmd", "args": ["/c", "npx", "-y", "@openserp/mcp"] in JSON.

For a remote server, add "env": { "OPENSERP_BASE_URL": "http://your-host:7000" } to the openserp JSON entry.

Tools: search, mega_search, fast_search, any_search, image_search, mega_image, extract, batch_extract, list_engines. Then just ask: “Search Google for the latest Postgres release, read the top 2 results and answer with links.”

Optional for Claude Code: copy skills/openserp-search to ~/.claude/skills/ so the agent searches, reads and falls back to another engine the same way every time.

Open WebUI

OpenSERP is a built-in web search provider. In Settings > Admin > Web Search pick openserp and set the URL (http://host.docker.internal:7000 if Open WebUI runs in Docker). See the Open WebUI guide.

In your own agent

A search tool for any LLM framework is a few lines with the SDK:

from openserp import OpenSERP

def web_search(query: str) -> list[dict]:
    """Search Google and return ranked results for the model."""
    with OpenSERP(base_url="http://localhost:7000") as client:
        res = client.search(engine="google", text=query, limit=10)
        return [
            {"rank": r.rank, "title": r.title, "url": r.url, "snippet": r.snippet}
            for r in res.results if r.type == "organic"
        ]

import { OpenSERP } from "@openserp/sdk";

const client = new OpenSERP({ baseUrl: "http://localhost:7000" });
const { results } = await client.search({ engine: "google", text: "openserp", limit: 5 });

More in examples: agent tools, RAG context, SEO rank tracking, extraction and image search.

Response Example

GET /google/search?text=how+do+mcp+servers+work&extract=1 (trimmed):

{
  "query": { "text": "how do mcp servers work", "engines_requested": ["google"] },
  "meta": { "took_ms": 4353, "engines_failed": [], "version": "2.1" },
  "results": [
    {
      "rank": 1,
      "type": "organic",
      "engine": "google",
      "title": "What Is the Model Context Protocol (MCP) and How It Works",
      "url": "https://www.descope.com/learn/post/mcp",
      "domain": "descope.com",
      "snippet": "MCP is an open standard that lets AI applications connect to external tools, data, and services through a client-server protocol built on JSON-…",
      "position": { "absolute": 1 },
      "extracted": {
        "format": "markdown",
        "content": "The Model Context Protocol (MCP) is an open standard that defines how AI applications connect to external tools, data sources, and services. MCP clients inside AI apps send requests to MCP servers, ..."
      }
    },
    {
      "rank": 2,
      "type": "organic",
      "engine": "google",
      "title": "No Dumb Questions: What is an MCP server and why do I ...",
      "url": "https://stackoverflow.blog/2026/05/08/no-dumb-questions-mcp",
      "domain": "stackoverflow.blog"
    }
  ]
}

Results keep their source engine and rank. Ads are typed separately from organic results; extract=N attaches up to N organic pages as Markdown and records per-page failures in extracted.error. Full schema in the OpenAPI spec.

Why OpenSERP

• Browser-backed search. Chromium loads the rendered SERP, including supported answer boxes, related searches and AI summaries. Raw HTTP mode is also available for Google, Yandex, Baidu and Ecosia.
• Six engines, one schema. Google, Bing, Yandex, Baidu, DuckDuckGo and Ecosia return the same JSON. Engine and rank survive a multi-engine merge, so you can see who ranked what.
• Search and read in one call. extract=N adds page Markdown under the top organic results, /extract/batch reads up to 20 URLs, and a dead link comes back as an error item instead of failing the batch.
• Yours to run. One Go binary or Docker image, with HTTP/SOCKS5 proxies, cache, retries, rate limits and circuit breakers. No per-query fees; you cover compute and proxies.

Compared to Paid Search APIs

✅ Available · 🟨 Partial, unconfirmed or requires integration · ❌ Unavailable

Search Endpoints

Engine names: google, yandex, baidu, bing, duckduckgo (also duck; ddg works in engines= and the CLI), ecosia.

Use a dedicated endpoint when the source engine matters, any for ordered fallback, or balanced to compare engines. Search supports JSON, Markdown, text and NDJSON, plus language, region, date, site and file filters.

Dedicated engine endpoints:

curl "http://127.0.0.1:7000/google/search?text=golang&limit=10"

Image search:

curl "http://127.0.0.1:7000/bing/image?text=golang+logo&limit=10"

Megasearch:

curl "http://127.0.0.1:7000/mega/search?text=golang&limit=10"

/mega/search returns the same envelope as engine endpoints plus clusters: results are deduplicated by normalized URL, and clusters keep the per-engine occurrences and ranks.

# Fast mode
curl "http://127.0.0.1:7000/mega/search?text=golang&mode=fast&engines=google,bing,yandex"

# Any mode
curl "http://127.0.0.1:7000/mega/search?text=golang&mode=any&engines=google,yandex,bing"

# Balanced mode with aggregation controls
curl "http://127.0.0.1:7000/mega/search?text=golang&mode=balanced&dedupe=true&merge=true"

# Advanced filtering
curl "http://127.0.0.1:7000/mega/search?text=golang&engines=google,bing&limit=20&date=20250101..20251231&lang=EN&region=US"

# Image megasearch
curl "http://127.0.0.1:7000/mega/image?text=golang+logo&limit=20"

List engines:

curl "http://127.0.0.1:7000/mega/engines"

URL extraction:

# Extract one URL as JSON
curl "http://127.0.0.1:7000/extract?url=https://example.com&mode=auto"

# Return clean page markdown
curl "http://127.0.0.1:7000/extract?url=https://example.com&format=markdown"

# Extract several URLs at once - returns a bare [{page_content, metadata}] array
# (Open WebUI external loader compatible); failed URLs become items with metadata.error
curl -X POST "http://127.0.0.1:7000/extract/batch" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://example.com","https://go.dev"],"mode":"fast"}'

# Embed extracted content under the top organic results
curl "http://127.0.0.1:7000/google/search?text=llm+observability&extract=2&format=markdown"

CLI Search

No server required - query an engine straight from the terminal. The CLI shares the same engines, formats, and filters as the API.

openserp search ecosia "weather in london" --format markdown

# Search results for "weather in london"

**Query:** weather in london - **Engines:** ecosia - **Took:** 866ms

## Results

### 1. London - BBC Weather

**bbc.com › weather › 2643743** - organic

Latest forecast for London ... Tonight will continue dry, and there will be mainly clear skies. Just a few patches of cloud drifting in from the north at times.

-> https://www.bbc.com/weather/2643743

### 2. London (Greater London) weather - Met Office

**weather.metoffice.gov.uk › forecast › gcpvj0v07** - organic

Remaining warm with light winds and dry. Possibly cloudy at times Monday and Tuesday, then Wednesday sunnier conditions are likely.

-> https://weather.metoffice.gov.uk/forecast/gcpvj0v07

# JSON is the default format
openserp search google "golang generics" --limit 20

# Plain text, German results
openserp search yandex "wetter berlin" --format text --lang DE --region DE

# Restrict to a site and stream NdJSON
openserp search bing "release notes" --site github.com --format ndjson

# Embed clean page content from the top 2 organic results
openserp search google "llm observability" --extract 2 --format markdown

# Browserless (raw HTTP) mode through a proxy
# (raw mode: google, yandex, baidu, ecosia)
openserp search ecosia "weather in london" --raw --proxy http://user:[email protected]:8080

Run openserp search --help for the full flag list. Results go to stdout, logs to stderr. Set verbosity with --log_level error|warn|info|debug|trace or OPENSERP_APP_LOG_LEVEL (CLI default: warn). serve also writes ./logs.txt unless app.save_log: false.

Query Parameters

Bing localizes by exit IP. lang sets its interface language; region sends a country hint except for US, CN and RU, which caused unrelated results in testing. For those locations, use a proxy in the target country.

Proxy Support

OpenSERP supports HTTP and SOCKS5 proxies.

./openserp serve --proxy socks5://127.0.0.1:1080
./openserp search bing "query" --proxy http://user:[email protected]:8080

Engines can return CAPTCHAs, rate limits or unrelated results. Browser mode does not eliminate these; try another engine or a proxy when needed.

Advanced proxy configuration is available in config.yaml. You can enable tagged proxy pools and per-request override via X-Use-Proxy: <tag> or X-Use-Proxy: direct.

API Docs

Once the server is running, the interactive docs are available locally:

• Swagger UI: http://127.0.0.1:7000/docs - full schemas, error shapes, and the /health, /ready, /stats/* endpoints
• OpenAPI YAML: http://127.0.0.1:7000/openapi.yaml

To browse the spec without running the server, see docs/openapi.yaml. For how OpenSERP works internally, see the architecture docs.

Contributing

Contributions are welcome. See docs/CONTRIBUTING.md.

License

MIT. See LICENSE.

Feedback & Updates

• GitHub Issues - bugs, feature ideas, and reproducible issues.
• [email protected] - private notes, longer feedback, or anything that does not fit GitHub Issues.
• Telegram - OpenSERP news, release notes, and project updates.

OpenSERP is free and open-source. Only links listed in this repository and on openserp.org are associated with the project.