Agent Search MCP

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, and any MCP-compatible client.

---

English · 中文 · 安装 · 文档

---

Quick Start

# 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>

---

Features

🆓 Free by Default

No API key required. Uses DuckDuckGo + Sogou search engines.

| Engine | Type | API Key | Coverage | |--------|------|---------|----------| | DuckDuckGo | Free | ❌ | Global | | Sogou | Free | ❌ | Chinese | | Brave Search | Paid (Free Tier) | Optional | Global | | Tavily | Paid (Free Tier) | Optional | Global |

🎯 Multi-Source Verification

Results are verified across multiple search engines. Each result includes a confidence score (1-3) based on how many engines returned it.

{
  "title": "Build an MCP Server",
  "url": "https://example.com/mcp",
  "snippet": "How to build MCP servers...",
  "confidence": 2  // Verified by 2 engines
}

💰 Save Tokens

Optimized output reduces token consumption by ~40-50%:

| Optimization | Savings | |-------------|---------| | Top-1 snippet per URL | ~25% | | Title truncation (≤100 chars) | ~15% | | Snippet truncation (≤200 chars) | ~15% | | Deduplication | ~10% | | Confidence filtering | ~10% |

🔧 Progressive Disclosure

Three tools, discoverable by agents:

| Tool | Purpose | When to Use | |------|---------|-------------| | free_search | Basic search | Quick questions | | free_search_advanced | Filtered search | Date ranges, domains, high confidence | | free_extract | URL extraction | Read full page content |

---

Tools

free_search

Basic web search with multi-source verification.

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

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
}

---

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:

[
  {
    "provider": "duckduckgo",
    "lastSuccess": 1719000000000,
    "errorCount": 0,
    "avgLatency": 450,
    "isHealthy": true
  }
]

---

Configuration

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | BRAVE_API_KEY | Brave Search API key (2000 free/month) | No | | TAVILY_API_KEY | Tavily API key (1000 free/month) | No | | LOG_LEVEL | Log level (info, debug) | No |

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

---

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
  ├── 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 / 文档

| Document | Description | |----------|-------------| | PRD | Product Requirements Document | | Architecture | Technical Architecture | | Plan | Implementation Plan | | Review Results | 5-Team Review Results | | Fork Plan | Fork & Modification Plan | | CHANGELOG | Version History |

---

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

---

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

Contributions welcome! Please read CONTRIBUTING.md first.

---

Keywords

MCP server, Model Context Protocol, AI agent search, free web search, multi-source search, DuckDuckGo MCP, Sogou search, token optimization, Hermes MCP, Claude Code MCP, Cursor MCP, AI tool, web search for agents, search aggregation, confidence scoring