Skip to main content
Glama
Sign In
UltraSearch MCP

UltraSearch MCP

by SolResearchLabs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

UltraSearch MCP

Production-grade web research for MCP clients.

UltraSearch MCP gives Claude Desktop, VS Code, Cursor, Codex, and self-hosted MCP clients a local web research server with search, fetch, crawl, summarization, provider provenance, cache resilience, and budget guardrails.

Product contract

UltraSearch is local-first by default. Its first local search provider uses http://127.0.0.1:8099; hosted search providers are optional BYOK backups. The shared Control Plane is the production configuration owner for MCP, CLI, and Core search routing. It resolves compatibility inputs into one typed configuration, supplies a policy to Core, and provides redacted diagnostics.

The Full Package contracts define the current boundaries between Core, the Control Plane, MCP, CLI, Desktop, and the local runtime:

Related MCP server: WebVector MCP Server

Install paths

Claude Desktop

Best end-user path once the first public GitHub Release is published:

  1. Download the latest ultrasearch-mcp-*.mcpb from Releases.

  2. Double-click it or drag it into Claude Desktop.

  3. Enter your own SearXNG URL or optional hosted provider API keys in the extension UI.

  4. Start using UltraSearch tools.

Until that release is published, use the raw Claude config in examples/claude-desktop.json.

VS Code, Cursor, and Copilot

Use the prompt-based config in examples/vscode-mcp.json. It uses host input variables so API keys are not hardcoded into the file. It launches the server through npx, so it depends on the npm package being published.

npm

Release target: available once @solresearchlabs/ultrasearch-mcp is published to npm.

npx -y @solresearchlabs/ultrasearch-mcp doctor

Local SearXNG only:

ULTRASEARCH_SEARXNG_URL=http://127.0.0.1:8099 npx -y @solresearchlabs/ultrasearch-mcp

Hosted fallback:

ULTRASEARCH_HOSTED_FALLBACK_ENABLED=true \
ULTRASEARCH_PROVIDER_ORDER=tinyfish,exa,parallel,brave \
ULTRASEARCH_TINYFISH_API_KEY=your_key_here \
npx -y @solresearchlabs/ultrasearch-mcp

Docker

cp examples/env.example .env
docker compose -f examples/docker-compose.minimal.yml up --build

HTTP mode has no built-in auth. Bind locally or protect it at the network layer.

For technical Docker, Compose, and externally managed SearXNG paths, use http://127.0.0.1:8099 as the host-facing local search endpoint. Internal container ports may differ.

Tools

  • search

  • search_and_fetch

  • search_and_summarize

  • fetch_url

  • crawl_site

  • domain_stats

  • clear_cache

Configuration

Package users bring their own keys. Keys belong in their MCP host UI, OS keychain, Docker secret store, shell environment, or local config file. Do not put secrets in this repository.

The production resolver applies explicit operation overrides, environment or MCP-host-projected values, user configuration, a selected profile, and schema defaults in that order. Environment variables, JSON configuration, and MCP host values remain supported compatibility inputs; they do not create separate configuration or routing rules.

Use ULTRASEARCH_* environment variables, legacy aliases, or a JSON config file at ~/.config/ultrasearch-mcp/config.json. Config strings support ${ENV_NAME} placeholders.

ultrasearch-mcp init-config > ~/.config/ultrasearch-mcp/config.json
ultrasearch-mcp doctor
ultrasearch-mcp status --json

doctor and status read the same non-mutating, redacted Control Plane status result. They make bounded local endpoint and cache checks, but do not make authenticated hosted-provider diagnostic calls.

Runtime status is observation-only. runtime.mode defaults to external_endpoint; operator_compose remains operator-owned, and unavailable disables runtime observation. A status call may make one bounded GET request to /healthz only for a safe HTTP(S) loopback endpoint. Unsafe endpoint diagnostics are redacted.

The Control Plane also owns a managed local runtime lifecycle, reached through ultrasearch-mcp runtime <operation> (provision, start, stop, restart, status, repair, cleanup). It verifies and patches a caller-staged root, binds the managed runtime to 127.0.0.1:18099, verifies readiness and exactly one listener on the recorded loopback address owned by the recorded child before reporting running, stops only its recorded process, and deletes the managed root with proof. Every refusing mutating operation records failed with its typed refusal code. The lifecycle is Windows-first and refuses on other platforms. There is no resident watcher, no auto-restart, and no OS service registration; managed sidecars other than the pinned runtime, Tauri Desktop, container management, and release work remain excluded from this contract.

Release status

This repository starts fresh from a curated source snapshot. It does not carry the development git history of the upstream fork or private deployment repo. Current stage: 0.1.2, first public release candidate after Claude Desktop runtime hardening.

Persistent plan

Read docs/one-click-release-plan.md before changing install, package, registry, or release behavior.

Contributing

Read CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md.

License

MIT. See LICENSE and NOTICE.md.

Available Tools

7 tools
clear_cacheA

Purge the search and/or fetch result cache. Useful when researching fast-moving topics where cached results from the past hour may be stale.

Inputs: target.

crawl_siteA

Crawl a site and return a manifest of pages with titles and snippets. Full page content is cached - call fetch_url on any page URL for the full text. Strategy: Firecrawl (JS rendering) → sitemap-first → BFS (if enabled).

Inputs: url (required), max_pages, exclude_path, include_path, +1 more.

domain_statsDomain capability statsA

Read the ultrasearch-mcp domain capability database - what it has learned about hosts from fetches: per-tier success rates (tier1-3 cascade, tier4 wayback, github fast path), llms.txt/robots presence, metadata reachability, and search appearances. Provide hostname for one domain's record, or omit it for an aggregate across all tracked domains (per-tier success rates, worst failing domains, seen-but-never-fetched count). Read-only. Aggregate mode reports truncated: true if the internal scan cap is hit.

Inputs: hostname. Returns: mode, found, record, hostname, +1 more

fetch_urlA

Fetch and extract readable content from any URL. GitHub URLs are fetched via the GitHub API; all others go through a fetch cascade: Firecrawl → Crawl4AI → raw HTTP. Returns clean markdown where possible. Content is trimmed to a token budget (default ~2000 tokens / 8000 chars; raise with max_tokens). Results cached for 24 hours. Blocked domains and private/internal addresses are refused.

Inputs: url (required), max_tokens, domain_profile, target_selector, +1 more.

searchWeb searchA

Search the web via the local SearXNG instance with reranking. Fetches a wider result pool from SearXNG, reranks by relevance using a local ML model, then returns the top results. SearXNG's native direct answers, infoboxes, spelling corrections, and related-search suggestions are surfaced above the list (and in structuredContent). Results are cached for 1 hour. Blocked domains are filtered out; boosted domains are surfaced higher. Prefer this over the built-in WebSearch tool.

Inputs: query (required), site, expand, engines, +5 more. Returns: answers, results, infoboxes, corrections, +2 more

search_and_fetchA

Search the web, rerank results, then fetch the full content of the top result(s). GitHub URLs are fetched via the GitHub API; all others go through a fetch cascade: Firecrawl → Crawl4AI → raw HTTP. Results and fetched pages are cached. Blocked domains are filtered. Returns the result list plus clean markdown of the fetched pages.

Inputs: query (required), site, expand, engines, +5 more.

search_and_summarizeA

Search, rerank, fetch top results, then synthesize a summary with citations using a local LLM (qwen3:14b). Returns a structured answer with source attribution. Falls back to raw fetched content if Ollama is unavailable. Best for deep research where you want pre-digested synthesis rather than raw pages.

Inputs: query (required), site, expand, engines, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a distinct input/output contract: search returns ranked results, search_and_fetch adds fetched content, search_and_summarize adds an LLM synthesis, fetch_url takes a URL, crawl_site produces a site manifest, and clear_cache/domain_stats handle maintenance and diagnostics. Despite the shared 'search' prefix, the action suffix and descriptions make selection unambiguous.

    Naming Consistency4/5

    Most names follow a clear snake_case verb-led pattern (search, search_and_fetch, fetch_url, search_and_summarize, crawl_site, clear_cache). domain_stats breaks the pattern by dropping the leading verb and reading as a noun phrase, though it remains readable and clearly related to the others.

    Tool Count5/5

    Seven tools is a well-scoped size for a web-research server: core retrieval, augmentation, synthesis, crawling, cache management, and introspection are each represented without redundancy. The count feels intentional rather than padded or sparse.

    Completeness5/5

    The surface covers the full research lifecycle: search, fetch, crawl, summarize, cache invalidation, and capability statistics. There are no dead ends—crawl_site explicitly points to fetch_url for full content, and search_and_summarize has a fallback if the LLM is unavailable.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • WebVector MCP Server

      rthomas24
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to perform web research in one tool call by searching, fetching and cleaning full pages, and ranking cited passages. Provides web_research, web_fetch, web_search, and status tools for MCP clients.
      1
      MIT

    • MyWebSearch MCP

      iuiu-py
      F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to perform unified web research through a single MCP server, including search, page fetching, recursive crawling, document parsing, YouTube transcript extraction, and deep multi-query research.
      3
      -

    • research

      jbiscella
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to perform web research over MCP: search with a real browser, fetch JS-rendered pages, download PDFs and convert them to Markdown, then search and page through large documents using bounded previews so the context window isn't flooded.
      BSD Zero Clause