searchio

searchio is a tool for search, page reading, and product lookup. Use it from the command line, from Python, or over HTTP. Use it as a person or as an AI agent. Search and reading need no API key.

Quick start for AI agents

An AI agent can set up searchio for its user in one pass. Follow these steps in order. Stop when the verify step passes.

1. Use Docker when Docker runs. Try:

docker run -i --rm ghcr.io/ioserviceslabs/searchio-mcp

The image holds the full system: fetch ladder, Rust engine sidecar, and a Chromium for the challenge tier. No other install step. Go to step 3.

2. No Docker: install from source. Needs Python 3.10 or newer.

pip install "searchio[mcp]"
curl -fsSL https://raw.githubusercontent.com/IOServicesLabs/searchio-engine/main/scripts/install.sh | sh

The pip command installs the searchio package with the MCP server from PyPI. The curl command adds the Rust engine sidecar at ~/.searchio/bin/se-serve (linux, macOS, Windows with Git Bash). The sidecar is the fast tier-2 backend. It is optional but recommended. For the latest development build use pip install "searchio[mcp] @ git+https://github.com/IOServicesLabs/searchio".

3. Add the MCP server to the client. Claude Desktop and Cursor use this config shape.

Docker:

{
  "mcpServers": {
    "searchio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/ioserviceslabs/searchio-mcp"]
    }
  }
}

Source install:

{
  "mcpServers": {
    "searchio": { "command": "searchio-mcp" }
  }
}

4. Verify. Restart the client. Ask: "Use searchio to search the web for the current time in Tokyo." Real results mean the setup works. An error about a missing command means the config points at a path that does not exist; fix the config and retry.

Note. npx @ioserviceslabs/searchio-mcp also works as the client command in step 3. The launcher starts the Docker image when Docker runs. Without Docker it starts the local install from step 2.

1. Install

You need Python 3.10 or newer.

Path A -- pip (one command):

pip install "searchio[mcp]"
searchio-mcp        # MCP server on stdio, ready for an LLM client

searchio doctor checks the install. The Rust engine sidecar is optional. Install it with the curl command in the quick start, step 2.

Path B -- Docker (no Python needed):

docker run -i --rm ghcr.io/ioserviceslabs/searchio-mcp              # stdio MCP
docker run -p 8080:8080 ghcr.io/ioserviceslabs/searchio-mcp \
  searchio-mcp --transport sse --host 0.0.0.0 --port 8080

No prebuilt image for your platform? Build from source:

docker build -t searchio https://github.com/IOServicesLabs/searchio.git

The image holds the full ladder: the Python tiers, the Rust engine sidecar, and a Chromium for the challenge tier. State (clearance, sessions) persists in a volume at /root/.searchio:

docker run -i --rm -v searchio-state:/root/.searchio ghcr.io/ioserviceslabs/searchio-mcp

Path C -- from source:

git clone https://github.com/IOServicesLabs/searchio.git
cd searchio
python -m venv .venv
.venv\Scripts\activate          # Windows
# source .venv/bin/activate     # macOS / Linux
pip install -e '.[mcp]'
searchio doctor

searchio doctor shows which fetch tiers work on your machine. Tier 0 is plain HTTP. Tier 1 adds TLS impersonation. Tier 2 adds a real browser for pages that block bots. Tier 2 starts on its own the first time it is needed.

The engine tier (optional, recommended)

Tier 2 uses the Rust searchio-engine sidecar when a se-serve binary is present. It boots in milliseconds and has no Chromium. The Docker image includes it. On a host install, one command adds it:

curl -fsSL https://raw.githubusercontent.com/IOServicesLabs/searchio-engine/main/scripts/install.sh | sh

The installer drops the binary at ~/.searchio/bin/se-serve and searchio finds it on its own. You can also set SEARCHIO_ENGINE_BIN to any binary.

MCP client setup

Point any MCP client at the server:

{
  "mcpServers": {
    "searchio": {
      "command": "searchio-mcp"
    }
  }
}

With Docker, use "command": "docker", "args": ["run", "-i", "--rm", "searchio"].

No Python at all? The npm wrapper picks a backend for you (Docker when present, else a local install):

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

2. Search

searchio search "best noise cancelling headphones 2026"
searchio search "rust async runtime comparison" --intent code
searchio search "artemis mission" --domains nasa.gov
searchio search "heat pump retrofit" --k 20 --json

You can set an intent: web (default), news, video, shopping, academic, code, forum, reference, local. You can also put site:nasa.gov in the query.

3. Read a page

searchio read https://example.com/some/article
searchio read https://example.com/paper.pdf --chars 20000

The command prints the readable text. It climbs walls, bot checks, and JavaScript-only pages on its own. If a page cannot be read, you get a clear reason. You do not get an empty page.

4. Products and listings

searchio items "sony wh-1000xm5"                    # one row per product across retailers
searchio items "dyson v15" --domains bestbuy.com --json
searchio marketplace "ford f-150" --city seattle    # Facebook Marketplace, browser-backed

5. Research with an AI swarm

This part costs money. Set one key:

set ANTHROPIC_API_KEY=...            # Windows
# export ANTHROPIC_API_KEY=...       # macOS / Linux
searchio research "What changed in the EU battery regulation this year, and who is affected?"

To use DeepSeek instead, set SEARCHIO_LLM_PROVIDER=deepseek and DEEPSEEK_API_KEY=.... The answer comes back with findings. Each finding cites pages the workers read.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗