evo-scry

MCP server for internet search via direct Google and DuckDuckGo HTML scraping with AI-powered result normalization.

Python. Zero API keys required for search. Optional AI summarization via GitHub Copilot token or local Ollama model.

Features

• 4 MCP Tools: web_search, search_google, search_duckduckgo, extract_content
• Multi-engine aggregation: Parallel search across Google + DuckDuckGo with deduplication and cross-engine ranking
• AI summarization: Optional result summaries via GitHub Copilot or local Ollama models
• Production-ready: Systemd service with full environment variable configuration
• Privacy-respecting: Direct HTML scraping, no third-party search APIs
• FastMCP pattern: Same architecture as evo-mem — SSE + streamable-http dual transport

Quick Start

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install
pip install -e .

# Run (STDIO transport for local MCP clients)
python -m evoscry.mcp_server

# Run (SSE transport for remote/systemd)
python -m evoscry.mcp_server --transport sse --port 3000

Claude Desktop / VS Code Configuration

{
  "mcpServers": {
    "evo-scry": {
      "command": "python",
      "args": ["-m", "evoscry.mcp_server"]
    }
  }
}

SSE Transport (remote)

{
  "mcpServers": {
    "evo-scry": {
      "url": "http://your-server:3000/sse"
    }
  }
}

MCP Tools

web_search

Search the internet using both Google and DuckDuckGo. Results are aggregated, deduplicated, and ranked.

| Parameter | Type | Required | Default | Description | |------------|----------|----------|---------|-------------| | query | string | yes | — | Search query | | engines | list | no | config | Engines to use | | max_results| int | no | 10 | Max results per engine | | language | string | no | "en" | Language code | | date_range | string | no | — | "day", "week", "month", "year" | | summarize | bool | no | false | AI-summarize results |

search_google / search_duckduckgo

Engine-specific search tools with the same parameters (minus engines and summarize).

extract_content

Fetch URLs and extract clean text or Markdown content.

| Parameter | Type | Required | Default | Description | |-----------|-----------------|----------|------------|-------------| | url | str \| list[str] | yes | — | URL(s) to extract | | format | string | no | "markdown" | "text" or "markdown" |

AI Summarization Setup

GitHub Copilot Token (recommended)

python -m evoscry.generate_copilot_token

Follow the prompts to authenticate via GitHub OAuth Device Flow. Add the generated token to your .env or systemd environment file.

Local Model (Ollama)

# In .env or systemd env:
EVOSCRY_LOCAL_MODEL_URL=http://localhost:11434
EVOSCRY_LOCAL_MODEL_NAME=llama3

Systemd Deployment

# Install (requires root)
sudo bash install.sh

# Configure
sudo vim /etc/evo-scry/evo-scry.env

# Start
sudo systemctl enable --now evo-scry

SSE endpoint: http://localhost:3000/sse Health check: http://localhost:3000/health

Configuration

All options via environment variables. See .env.example for the full list.

| Variable | Default | Description | |----------|---------|-------------| | EVOSCRY_TRANSPORT | stdio | stdio, sse, or streamable-http | | EVOSCRY_HOST | 0.0.0.0 | HTTP bind address | | EVOSCRY_PORT | 3000 | HTTP port | | EVOSCRY_SEARCH_ENGINES | duckduckgo | Enabled engines | | EVOSCRY_MAX_RESULTS | 10 | Results per engine | | EVOSCRY_REQUEST_DELAY_MS | 1000 | Rate limiting delay | | EVOSCRY_USER_AGENT | rotate | UA rotation | | EVOSCRY_PROXY_URL | — | HTTP/SOCKS5 proxy | | EVOSCRY_COPILOT_TOKEN | — | Copilot API token | | EVOSCRY_COPILOT_REFRESH_TOKEN | — | GitHub OAuth token for auto-refresh | | EVOSCRY_LOCAL_MODEL_URL | — | Ollama endpoint | | EVOSCRY_LOG_LEVEL | info | Log verbosity | | EVOSCRY_CACHE_TTL_SECONDS | 300 | Cache TTL |

License

MIT