Agent Search MCP

🔍 Free multi-source search for AI agents — multi-source verification, token savings, MCP native.

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

English · 中文 · 安装 · 工具文档 · 竞品对比

Why Agent Search MCP

AI agents need to search the internet. But existing solutions have problems:

• Tavily — Great quality, but $0.01/search adds up fast. Monthly cost: $20-50+.
• Exa — Semantic search is powerful, but $50/month minimum.
• Brave Search — 2000 free queries/month, then $3/1000. Not enough for heavy use.
• DDG MCP — Single source, no verification, no dedup, results vary wildly.
• open-websearch — 13 engines, but 300MB+ dependency tree, no token optimization.

Agent Search MCP solves this differently:

1. Free + high quality — DuckDuckGo + Sogou as core engines, no API key needed
2. Multi-source verification — Results cross-checked across engines, each result gets a confidence score (1-3)
3. Token optimization — Title ≤100 chars, snippet ≤200 chars, dedup removes redundancy. Saves ~40-50% tokens.
4. MCP native — Built for Model Context Protocol from day one. Zero config, works out of the box.
5. Self-hostable — No data sent to third parties. Run it on your own VPS.
6. Security built-in — Prompt injection detection, output boundary markers, phishing URL filtering.

Who is this for?

• AI agent developers (Hermes, OpenClaw, custom agents)
• IDE users who want AI-powered search (Claude Code, Cursor, Windsurf)
• Anyone building MCP-compatible tools
• Users who need Chinese web search (Sogou integration)

The math: If you search 100 times/day, Tavily costs ~$1/day. Agent Search MCP costs $0. Over a year, that's $365 saved.

为什么选择 Agent Search MCP

AI Agent 需要搜索互联网。但现有方案都有问题：

• Tavily — 质量好，但每次搜索 $0.01，月费 $20-50+
• Exa — 语义搜索强，但最低 $50/月
• Brave Search — 2000 次/月免费，之后 $3/1000，重度使用不够
• DDG MCP — 单源，无验证，无去重，结果质量不稳定
• open-websearch — 13 引擎，但 300MB+ 依赖，无 token 优化

Agent Search MCP 的解决方案：

1. 免费 + 高质量 — DuckDuckGo + Sogou 为核心，无需 API Key
2. 多源验证 — 跨引擎交叉验证，每个结果有置信度评分（1-3）
3. Token 优化 — 标题 ≤100 字符，摘要 ≤200 字符，去重去除冗余。节省 ~40-50% token
4. MCP 原生 — 基于 Model Context Protocol 构建，零配置开箱即用
5. 可自托管 — 数据不经过第三方，可在自有 VPS 运行
6. 内置安全 — Prompt 注入检测、输出边界标记、钓鱼 URL 过滤

适用人群：

• AI Agent 开发者（Hermes、OpenClaw、自定义 Agent）
• IDE 用户（Claude Code、Cursor、Windsurf）
• 构建 MCP 兼容工具的开发者
• 需要中文搜索的用户（搜狗集成）

成本对比： 如果每天搜索 100 次，Tavily 月费约 $30。Agent Search MCP 完全免费。一年省 $365。

Competitor Comparison

Key differences:

1. Free by default — No API key, no credit card, no limits. DuckDuckGo + Sogou work out of the box.
2. Multi-source verification — Results from multiple engines are cross-checked. Confidence score tells you how reliable a result is.
3. Token optimization — Smart truncation and dedup reduce token consumption by ~40-50%. This is crucial for cost-sensitive applications.
4. Chinese support — Sogou engine provides native Chinese web search. Not a translation layer.
5. Progressive disclosure — 3 tools at different complexity levels. Agents discover capabilities on-demand (Exa model).
6. Security — Built-in protection against prompt injection, phishing URLs, and output boundary markers.

Quick Start

Prerequisites

• Node.js >= 18
• Python 3 with ddgs library:

pip install ddgs

Install

# Option 1: npx (recommended)
npx agent-search-mcp

# Option 2: global install
npm install -g agent-search-mcp

Platform Setup

<details> <summary><b>Hermes</b></summary>

# ~/.hermes/config.yaml
mcp_servers:
  agent-search:
    command: npx
    args: ["agent-search-mcp"]

</details>

<details> <summary><b>Claude Code</b></summary>

// ~/.claude/mcp.json
{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

</details>

<details> <summary><b>Cursor</b></summary>

// .cursor/mcp.json
{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

</details>

<details> <summary><b>Windsurf</b></summary>

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

</details>

<details> <summary><b>OpenClaw</b></summary>

// openclaw.config.ts
{
  mcpServers: {
    "agent-search": {
      command: "npx",
      args: ["agent-search-mcp"]
    }
  }
}

</details>

<details> <summary><b>Codex</b></summary>

// ~/.codex/mcp.json
{
  "mcpServers": {
    "agent-search": {
      "command": "npx",
      "args": ["agent-search-mcp"]
    }
  }
}

</details>

Features

• Free by default — DuckDuckGo + Sogou as core engines, no API key required. Brave and Tavily available as optional paid fallback.
• Multi-source verification — Results cross-checked across engines, each result gets a confidence score (1-3) based on how many sources returned it.
• Token optimization — Title truncation (≤100 chars), snippet truncation (≤200 chars), URL + title dedup. Saves ~40-50% tokens.
• Progressive disclosure — 3 tools at different complexity levels. free_search for quick queries, free_search_advanced for filtered search, free_extract for page content. Agents discover capabilities on-demand.
• Fallback chain — Free engines first, paid engines as backup. Automatic merge, dedup, and scoring.
• Health monitoring — Real-time provider health tracking. Unhealthy providers filtered automatically.
• Security — Prompt injection detection, output boundary markers, phishing URL filtering, and security metadata on every response.
• CLI tool — Use as a command-line tool for terminal search, web extraction, and HTTP server.

CLI Usage

free-agent-search-mcp also works as a CLI tool.

Install

npm install -g agent-search-mcp

Search

# Basic search
fasm search "TypeScript MCP server"

# With options
fasm search "query" --count 5 --engines bing,baidu

# JSON output
fasm search "query" --json

Extract Web Page

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

Start HTTP Server

fasm serve --port 8080

Help

fasm --help

Tools

free_search

Basic web search with multi-source verification.

{
  "query": "TypeScript MCP server",
  "count": 5
}

Returns: Array of search results with confidence scores.

free_search_advanced

Advanced search with filters.

{
  "query": "MCP server",
  "count": 10,
  "min_confidence": 2,
  "time_range": "week",
  "language": "zh",
  "include_domains": ["github.com"],
  "exclude_domains": ["reddit.com"]
}

Parameters:

• min_confidence (1-3): Only return results verified by N+ sources
• time_range: day, week, month, year
• language: auto, en, zh
• include_domains: Only search these domains
• exclude_domains: Exclude these domains

free_extract

Extract full content from a URL as Markdown.

{
  "url": "https://example.com/article",
  "max_length": 5000
}

Returns: Markdown content with metadata.

Resources

search://capabilities

Returns a Markdown document describing all available tools and features. Agents can discover capabilities on-demand.

search://health

Returns JSON with health status of each search provider. Useful for monitoring and debugging.

Configuration

Environment Variables

Zero config works — no API keys needed for basic search.

With Paid Engines

Set environment variables to enable fallback to paid engines when free results are insufficient:

export BRAVE_API_KEY=your_key_here
export TAVILY_API_KEY=your_key_here

Dependencies

Note: ddgs is a Python library called via subprocess. It must be installed separately:

pip install ddgs

Architecture

Agent
  ↓ MCP Protocol (stdio)
MCP Server
  ├── Tools Layer (progressive disclosure)
  │   ├── free_search (default)
  │   ├── free_search_advanced (optional)
  │   └── free_extract (optional)
  ├── Aggregation Layer
  │   ├── Top-1 Snippet merge
  │   ├── URL + Title dedup
  │   ├── Scoring + Confidence
  │   └── Output truncation
  ├── Security Layer
  │   ├── Prompt injection detection
  │   ├── Output boundary markers
  │   ├── Phishing URL filtering
  │   └── Security metadata
  ├── Fallback Chain
  │   ├── Phase 1: Free engines (DDG + Sogou)
  │   └── Phase 2: Paid engines (Brave + Tavily)
  └── Infrastructure
      ├── Cache (LRU, 60s TTL)
      ├── Rate Limiter (1s per provider)
      ├── Health Tracker
      └── SSRF Protection

Documentation / 文档

Development

# Clone
git clone https://github.com/lennney/agent-search-mcp.git
cd agent-search-mcp

# Install
npm install

# Build
npm run build

# Test
npm test

# Run
npm start

Roadmap

• [ ] v0.1.0 — Initial release with DDG + Sogou
• [ ] v0.2.0 — Brave + Tavily fallback
• [ ] v0.3.0 — Health monitoring + rate limiting
• [ ] v1.0.0 — Stable release with documentation
• [ ] v1.1.0 — Plugin system for custom engines
• [ ] v2.0.0 — Browser-based extraction (Playwright)

License

Apache License 2.0

Based on open-websearch by Aas-ee.

Copyright 2025 Open-WebSearch MCP Server Contributors
Based on open-websearch by Aas-ee (Apache 2.0).
Modified by Agent Search MCP Contributors.
Copyright 2026 Agent Search MCP Contributors

Contributing