English · 简体中文

search2ai

A self-hosted search gateway for AI agents and AI clients.

Connect the search and page extraction services you configure through MCP, an HTTP API, or a JavaScript / TypeScript library. When a provider is rate limited, times out, or fails, the gateway tries the next one in your configured order and reports which service answered and why others failed.

Search endpoints return structured results and page content for your agent or application to use. An optional chat proxy also lets models that support tool calling search the web while answering.

• Consistent results: title, url, snippet, and optional fields such as date and content.
• Search, news, and page content: search, news, and crawl, depending on the configured providers.
• Your choice of providers: supply service URLs or credentials as needed; unconfigured providers are never enabled automatically.
• Fallback and caching: separate chains per operation, in-memory caching, and Cloudflare KV caching.
• Flexible integration: local MCP, a standalone HTTP service, direct library calls, and mountable Hono routes.
• Existing API clients: supported Exa, Tavily, Search1API, SearXNG and Firecrawl single-page calls can use dedicated HTTP API / SDK compatibility endpoints.

Looking for hosted search? Search1API is this project's companion hosted service for search, news, and page extraction. Use its API directly or configure it as a search2ai provider. It also offers hosted compatible APIs to help existing integrations switch with minimal changes. The examples below use Search1API; you can choose any other supported provider.

Website · Quick start · Choose an integration · Providers and configuration · HTTP API · API / SDK compatibility · Deployment · Chat proxy · Upgrading · Development and contributing

Quick start

The local CLI and npm package require Node.js ≥ 22.18. Configure at least one provider that supports the operation you need. In the current version, search requests return 503 when no search provider is configured.

Create .env in your working directory with your search provider key:

SEARCH1API_KEY=your_provider_key

Start a local HTTP service:

npx -y search2ai serve --host 127.0.0.1

Search from another terminal:

curl http://localhost:3014/v1/search \
  -H 'Content-Type: application/json' \
  -d '{"query":"hono cloudflare workers","max_results":3}'

The response's results contain titles, URLs, and excerpts. This calls only the search provider and needs no model API key. The same service exposes /v1/news, /v1/crawl, and the remote MCP endpoint /mcp.

The CLI reads .env.local and .env from its working directory. Existing environment variables take priority, followed by .env.local, then .env. See .env.template for the full configuration template.

Choose an integration

For AI clients: MCP

For clients using the mcpServers configuration format, add:

{
  "mcpServers": {
    "search2ai": {
      "command": "npx",
      "args": ["-y", "search2ai", "mcp"],
      "env": {
        "SEARCH1API_KEY": "your_provider_key"
      }
    }
  }
}

Th

... View full README on GitHub