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