MagicalGirlWebOracle
Routes Chinese-language web search queries to Baidu through the SearXNG engine matrix.
Routes Chinese-language web search queries to Bilibili through the SearXNG engine matrix.
Provides a self-hosted metasearch backend and fallback for web search, including routing Chinese queries through a configurable SearXNG engine matrix.
Routes Chinese-language web search queries to Sogou through the SearXNG engine matrix.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
MagicalGirlWebOracle ๐
![]()
English ยท ็ฎไฝไธญๆ ยท ๆฅๆฌ่ช
MagicalGirlWebOracle is a self-hosted web search, deep research, and page fetching router for AI agents, exposed through a single Model Context Protocol endpoint. It selects providers, accounts, and keys automatically โ the agent just asks.
The hard rule is simple: use free quotas only, and never create a bill.
ALLOW_PAID_OVERAGE=false is the default and the only supported value.
Highlights
One endpoint, many backends โ You.com MCP, SearXNG, Exa, Tavily, Jina Reader, Crawl4AI, and Firecrawl behind one MCP/CLI interface.
Free-tier aware routing โ scores quality, cost, remaining quota, health, and latency; expensive free credits are reserved for harder questions.
Self-hosted fallback โ SearXNG + Crawl4AI keep search and fetching working even when every cloud quota is exhausted.
Chinese internet search โ Chinese queries are routed to a SearXNG engine matrix (Baidu, Bing, Quark, Sogou, Bilibili, 360, โฆ).
Evidence first โ research responses contain real source URLs and excerpts, never fabricated citations.
Multi-account / multi-key ledger โ optional per-account quota pools, encrypted credentials, official balance snapshots, and key rotation.
Fluent UI admin dashboard โ light/dark themes, English / Simplified Chinese / Traditional Chinese / Japanese, quota and call inspection.
Auditable but private โ query text is hashed by default; no telemetry and no outbound calls except the providers you configure.
Related MCP server: Agent Search
How it works
Agent (Claude Code / Codex / any MCP client)
โ MCP (stdio or streamable HTTP) / CLI
โผ
Oracle
โโโ SearchRouter โโ score candidates โ concurrent calls โ dedup/merge โ rerank
โ providers: you_mcp / searxng / exa / tavily
โโโ FetchRouter โโ light_http โ jina_reader โ crawl4ai โ firecrawl
โโโ Quota ledger โโ SQLite: reservations, settlement, windows, per-key usage
โโโ HealthTracker โ healthy โ degraded โ unavailable โ cooldown recovery
โโโ Dedup โ URL canonicalization + cross-provider agreementDashboard
Light | Dark |
|
|
Quick start
Docker Compose (recommended)
git clone https://github.com/LingMoe404/MagicalGirlWebOracle.git
cd MagicalGirlWebOracle
cp .env.example .envEdit .env:
Set
MCP_AUTH_TOKENto a long random value if other machines will connect.Add the provider keys you have (
EXA_API_KEY,TAVILY_API_KEY,FIRECRAWL_API_KEY,JINA_API_KEY,YDC_API_KEY); every key is optional.Set
SEARXNG_URL/CRAWL4AI_URLif you run those services.MCP_BIND_IPdefaults to127.0.0.1. Set it to0.0.0.0(or a VPN/LAN address) only when you intentionally expose the service.
docker compose up -d --build
curl -fsS http://127.0.0.1:28288/healthzMCP endpoint: http://127.0.0.1:28288/mcp.
The one-command script builds the image, auto-detects SearXNG/Crawl4AI, generates a token on first run, starts the service, and runs diagnostics:
bash deploy.shDocker Hub image
ORACLE_IMAGE=lingmoe404/magicalgirl-web-oracle:0.1.0 \
docker compose up -d --no-buildPyPI (local stdio)
pip install magicalgirl-web-oracle
# create .env in the working directory, or export the variables directly
python -m magicalgirl_web_oracle.mcp_server.serverConnect an MCP client
Local stdio:
{
"mcpServers": {
"magicalgirl-web-oracle": {
"command": "python",
"args": ["-m", "magicalgirl_web_oracle.mcp_server.server"]
}
}
}Shared HTTP:
{
"mcpServers": {
"magicalgirl-web-oracle": {
"type": "streamable-http",
"url": "http://<host>:28288/mcp",
"headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
}
}
}Omit headers when MCP_AUTH_TOKEN is empty. See
examples/mcp/ for copy-paste files.
CLI
magicalgirl-web search "rust async runtime benchmark" --mode high
magicalgirl-web search "ๅฐ็ฑณ SU7 ่ฏๆต" # Chinese engine routing
magicalgirl-web research "้ๅญ่ฎก็ฎไธปๆต่ทฏ็บฟๅฏนๆฏ" # evidence pack
magicalgirl-web fetch "https://some-js-heavy-site.com"
magicalgirl-web crawl "https://docs.example.com" --max-pages 20
magicalgirl-web status # health/quota table
magicalgirl-web doctor # connectivity diagnosticsMCP tools
Tool | Purpose |
| Search with automatic routing. Modes: |
| Multi-hop research; returns sources, excerpts, and real citations. |
| Fetch one page through the escalation ladder. |
| Depth-limited crawl; prefers self-hosted Crawl4AI. |
| Provider health, quota, scheduling, and cache status. |
| Force one provider for comparison. |
Configuration
Configuration lives in .env plus config/providers.yaml and
config/router_policy.yaml. All provider keys are optional; a missing key just
removes that provider from routing.
See docs/configuration.md for every environment variable, defaults, cache/scheduling options, and the YAML files.
Multi-account dashboard
The optional dashboard manages multiple provider accounts and keys, encrypted with a Fernet master key, and shows official balance snapshots, alerts, call traces, cache counters, and scheduling decisions.
# .env: ORACLE_ADMIN_TOKEN, ORACLE_VAULT_KEY, ORACLE_ACCOUNTS_FILE
docker compose --profile admin up -dOpen https://127.0.0.1:28443/admin/ and sign in with ORACLE_ADMIN_TOKEN.
See docs/multi-key-setup.md for the account
model, key management, backups, and security notes.
Security and privacy
The HTTP server binds to
127.0.0.1by default; expose it only on a trusted network or VPN and setMCP_AUTH_TOKEN.The admin token is independent from the MCP token; empty disables the UI.
Provider keys live in
.env, environment variables, or Fernet ciphertext in the local ledger. They are never returned by APIs or written to logs.Query text is not stored unless
STORE_QUERY_TEXT=true; the default is a salted hash.402/ payment-required responses are classified as quota exhaustion. There is no code path that enables paid overage.The service has no telemetry and makes no network requests except to the providers and self-hosted services you configure.
Read SECURITY.md before exposing the service beyond a single machine.
Deployment and operations
See docs/deployment.md for Docker Compose, the optional HTTPS admin listener, SearXNG/Crawl4AI setup, VPN/reverse-proxy guidance, backups, upgrades, and troubleshooting.
Limitations and responsible use
This is a
0.1.xbeta; interfaces may change before1.0.Free-tier quotas and provider APIs can change without notice. Use the service in accordance with each provider's terms. The project cannot guarantee that any provider remains free.
The container currently runs as root; the bundled admin listener uses a self-signed certificate by default.
โOracleโ in the project name is descriptive. This project is not affiliated with Oracle Corporation or with any search provider.
Development
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest
cd frontend
npm ci
npm run build # writes the admin bundle into src/.../admin/static/The default test suite is fully mocked and needs no keys or network access.
License
MIT โ see LICENSE. The icon artwork in
assets/icon/ is original work by LingMoe404 and is distributed
under the same license. Third-party notices are in
THIRD_PARTY_NOTICES.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
This server cannot be deployed
Maintenance
Related MCP Connectors
Free web search for AI agents. No API key required. Hosted MCP in active development.
Multi-engine search for AI agents. Trust scoring, local corpus, MCP-native. Self-hostable, BYOK.
Your agent needs the open web โ searched by more than one engine, and read as clean markdown rather than raw HTML. **What you can ask for** โข "Search this question with two providers and tell me where they disagree." โข "Scrape these 40 URLs into markdown, in one batch." โข "Crawl this documentation site and give me every page." โข "Do deep research on this topic and cite the sources." โข "Find the academic papers behind this claim." **How to use it** Point any MCP client at https://mcp.aisa.one/search/mcp and sign in with OAuth โ there is no key to create or paste. 30 tools across several independent providers: Tavily and Exa search, answers, contents and agent runs; Firecrawl scrape, batch scrape, crawl, map and search; Perplexity Sonar, Sonar Pro, reasoning and deep research; Oxylabs AI search and LLM jobs; OpenAI and Anthropic web search; and scholarly search. **Why this rather than the source** Several independent indexes behind one account, because one engine's blind spot is not visible from inside it. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Find the page here, then ask the same agent who links to it or how much traffic it gets โ without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/seo-serp/mcp for the Google results page itself, https://mcp.aisa.one/seo-serp-other-engines/mcp for Bing, Baidu and Naver.
Web search API and MCP server for developers building AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceA local-first, no-API-key MCP server that enables LLMs to search the web, fetch pages, and read documents using multiple engines and smart fallbacks.611181MIT
- AlicenseNot gradedqualityDmaintenanceA self-hosted, MCP-native web-search backend for AI agents that provides meta-search, clean extraction, RAG with citations, and GitHub project selection.5MIT
- AlicenseNot gradedqualityFmaintenanceMCP server enabling local-first web search, fetch, extract, and caching with citeable excerpts, no API key required. Supports research workflows for agents and apps.96 npm1MIT
- AlicenseAqualityCmaintenanceA self-hosted MCP server for web search with multi-engine support, combining search, URL fetching, and deep research along with proxy routing and deduplication.3MIT

