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.

🎯 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%:

🔧 Progressive Disclosure

Three tools, discoverable by agents:

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

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

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