Agent Search MCP

🔍 11 search engines, 8 free, one MCP server. Zero API keys. Chinese search. Multi-source verification. Streamable HTTP. npm install is enough.

Works with Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Codex, Hermes, and any MCP-compatible client.

⭐ Star on GitHub — it helps others discover the project!

English · 中文 · Tools · CLI · Engines · Config

Quick Start

Prerequisites

• Node.js >= 18 — that's it. No Python, no API keys, no Docker required.

Install

# npx (no install)
npx agent-search-mcp

# Global install
npm install -g agent-search-mcp

Configure Your Client

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

mcp_servers:
  agent-search:
    command: npx
    args: ["agent-search-mcp"]

{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

Why Agent Search MCP

AI agents need to search the web. But existing options have problems:

Agent Search MCP is different:

Engines

Tools

All tools are read-only and idempotent with MCP 2025 annotations.

Key Features

Waterfall Search (3 phases, confidence-gated):

1. Phase 1: DDG + Sogou → check confidence
2. Phase 2: Bing + Baidu → check
3. Phase 3: Brave + Tavily + Exa (paid only)

Stops as soon as results are sufficient. Saves 50-75% engine calls.

Confidence Scoring (1-3):

• 1: Single source
• 2: Verified by 2+ sources (recommended)
• 3: Highly verified by 3+ sources

Structured Errors: Engine failures return typed errors (timeout, rate_limited, permission_denied, etc.) with actionable suggestions — agents can self-recover.

Configuration

Environment Variables

Zero config works — no API keys needed for the 8 free engines.

Tool Visibility

Control which tools your agent can see:

# Only search tools
ENABLED_TOOLS=free_search,free_search_advanced,free_search_news

# Disable specific tools
DISABLED_TOOLS=free_extract,fetch_github_readme

# Enable only one fetch tool
ENABLED_TOOLS=fetch_csdn_article

Engine Filtering

# Only use Chinese engines
ALLOWED_ENGINES=sogou,baidu

# Exclude specific engines
DENIED_ENGINES=yandex,mojeek

CLI

agent-search-mcp also works as a standalone CLI tool (fasm).

# Search
fasm search "TypeScript MCP server"
fasm search "query" --count 5 --engines bing,baidu --json

# Extract
fasm extract "https://example.com"
fasm extract "https://example.com" --json

# HTTP server
fasm serve --port 8080

Architecture

Agent (Claude Code, Cursor, etc.)
  ↓ MCP Protocol (stdio / Streamable HTTP)
MCP Server
  ├── Tools Layer
  │   ├── free_search / free_search_advanced / free_search_news
  │   ├── search_with_synthesis
  │   ├── free_extract
  │   └── fetch_github_readme / fetch_csdn_article / fetch_juejin_article
  ├── Aggregation Layer
  │   ├── Waterfall Search (3-phase confidence-gated)
  │   ├── Cross-Engine Scoring (frequency + domain authority)
  │   ├── Dedup (URL + title)
  │   ├── Content Enrichment (Jina Reader)
  │   └── Query Expansion (rule-based, 4 strategies)
  ├── Engine Layer (11 engines)
  │   ├── Free: DDG, Sogou, Bing, Baidu, Wikipedia, Startpage, Yandex, Mojeek
  │   └── Paid: Brave, Tavily, Exa
  └── Infrastructure
      ├── Health Tracker (per-engine circuit breaking)
      ├── Rate Limiter (adaptive concurrency)
      ├── Cache (LRU, 60s TTL, 1000 entries)
      ├── SSRF Protection (URL validation)
      └── Security (injection detection, boundary markers)

Development

git clone https://github.com/lennney/agent-search-mcp.git
cd agent-search-mcp
npm install
npm run build
npm test          # 448 tests, 40 files
npm run dev       # stdio mode
npm run dev:http  # HTTP mode (port 3000)

Stats

🔗 Companion Tools

🛡️ mcp-slim-guard — Add security + compression to your MCP stack

npm install -g mcp-slim-guard
mcp-slim-guard init
mcp-slim-guard start

Pair agent-search-mcp with mcp-slim-guard to get:

AI Agent → mcp-slim-guard (security + compression) → agent-search-mcp

License

MIT