fast-web-search-mcp

A production-ready Model Context Protocol server for free web search, news search, and webpage content extraction.

Features · Quick Start · Integration · Configuration · Security · Docs

Why fast-web-search-mcp?

Most MCP search servers require paid API keys, Docker containers, or headless browsers. fast-web-search-mcp provides free, fast, local web search with zero external dependencies beyond Node.js.

Features

• Web Search — DuckDuckGo primary with Bing fallback and Wikipedia reference lookup
• News Search — Date-sensitive news results with publication metadata
• Page Fetching — Readability extraction with Markdown or plain text output
• Combined Research — Search, rank, and fetch top results in one call
• Intelligent Caching — In-memory LRU cache with configurable TTL
• Request Coalescing — Deduplicates concurrent identical searches
• Rate Limiting — Per-provider throttling with exponential backoff
• Result Deduplication — URL canonicalization and title similarity matching
• SSRF Protection — Blocks private IPs, localhost, cloud metadata endpoints
• Provider Fallback — Automatic failover when a provider is unavailable
• Zero Runtime Dependencies — No Python, no Docker, no browser engine

Quick Start

Install

# Global install (recommended)
npm install -g fast-web-search-mcp

# Or run directly without installing
npx -y fast-web-search-mcp

Requirements

Verify Installation

# Confirm the binary is available
fast-web-search-mcp --version

# Or run directly
npx fast-web-search-mcp --version

Integration

Add fast-web-search-mcp to your AI coding assistant. Select your platform below:

{
  "mcpServers": {
    "fast-web-search": {
      "command": "fast-web-search-mcp",
      "env": {
        "FWSMCP_LOG_LEVEL": "warn",
        "FWSMCP_REDACT_QUERIES": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "fast-web-search": {
      "command": "fast-web-search-mcp",
      "env": {
        "FWSMCP_DEFAULT_REGION": "us-en",
        "FWSMCP_DEFAULT_LANGUAGE": "en",
        "FWSMCP_REDACT_QUERIES": "true"
      }
    }
  }
}

claude mcp add fast-web-search -- fast-web-search-mcp

{
  "mcpServers": {
    "fast-web-search": {
      "command": "fast-web-search-mcp",
      "env": {
        "FWSMCP_LOG_LEVEL": "warn",
        "FWSMCP_DEFAULT_REGION": "us-en",
        "FWSMCP_DEFAULT_LANGUAGE": "en"
      }
    }
  }
}

[mcp_servers.fast-web-search]
command = "fast-web-search-mcp"
env = { FWSMCP_LOG_LEVEL = "warn", FWSMCP_REDACT_QUERIES = "true" }

codex mcp add fast-web-search -- fast-web-search-mcp

{
  "mcp": {
    "fast-web-search": {
      "type": "local",
      "command": ["fast-web-search-mcp"],
      "enabled": true,
      "environment": {
        "FWSMCP_DEFAULT_REGION": "us-en",
        "FWSMCP_DEFAULT_LANGUAGE": "en",
        "FWSMCP_REDACT_QUERIES": "true",
        "FWSMCP_SAFE_SEARCH": "moderate"
      }
    }
  }
}

{
  "mcpServers": {
    "fast-web-search": {
      "command": "fast-web-search-mcp",
      "args": [],
      "env": {
        "FWSMCP_LOG_LEVEL": "warn",
        "FWSMCP_REDACT_QUERIES": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "fast-web-search": {
      "command": "fast-web-search-mcp",
      "env": {
        "FWSMCP_LOG_LEVEL": "warn"
      }
    }
  }
}

{
  "servers": {
    "fast-web-search": {
      "command": "fast-web-search-mcp",
      "env": {
        "FWSMCP_LOG_LEVEL": "warn"
      }
    }
  }
}

MCP Tools

Tool Parameters

Configuration

All configuration is environment-based. No config files required.

Optional JSON Configuration

For complex setups, point FWSMCP_CONFIG_FILE to a JSON file:

{
  "defaults": {
    "region": "us-en",
    "language": "en",
    "safeSearch": "moderate"
  },
  "providers": {
    "order": ["duckduckgo", "bing", "wikipedia"],
    "strategy": "fallback"
  },
  "cache": {
    "enabled": true,
    "maxEntries": 250,
    "searchTtlMs": 900000
  },
  "limits": {
    "maxSearchResults": 25,
    "maxFetchCharacters": 100000
  },
  "privacy": {
    "redactQueriesInLogs": true
  }
}

Priority: Environment variables > JSON config file > defaults.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│            (Claude Code / Codex / OpenCode)              │
└─────────────────────┬───────────────────────────────────┘
                      │ stdio (JSON-RPC)
                      ▼
┌─────────────────────────────────────────────────────────┐
│               fast-web-search-mcp                        │
│                                                         │
│  ┌─────────┐  ┌──────────┐  ┌───────────┐  ┌────────┐ │
│  │  Tools   │  │  Cache   │  │ Coalescer │  │ Limiter│ │
│  │ 5 tools  │  │ LRU+TTL  │  │ Dedup     │  │ Per-   │ │
│  │          │  │          │  │ inflight  │  │ provider│ │
│  └────┬─────┘  └──────────┘  └───────────┘  └────────┘ │
│       │                                                  │
│       ▼                                                  │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Orchestrator Pipeline                │    │
│  │  Validate → Cache → Coalesce → Select → Execute  │    │
│  │  → Normalize → Filter → Dedup → Rank → Return    │    │
│  └─────────────────────┬───────────────────────────┘    │
│                        │                                 │
│       ┌────────────────┼────────────────┐               │
│       ▼                ▼                ▼               │
│  ┌─────────┐    ┌──────────┐    ┌────────────┐         │
│  │ DuckDuck │    │   Bing   │    │ Wikipedia  │         │
│  │   Go     │    │          │    │ REST API   │         │
│  │ (HTML)   │    │ (HTML)   │    │            │         │
│  └─────────┘    └──────────┘    └────────────┘         │
│       │                │                                 │
│       ▼                ▼                                 │
│  ┌─────────────────────────────────────────────────┐    │
│  │            HTTP Client (Node fetch)               │    │
│  │   Timeout · Body Limit · Redirect · SSRF Block   │    │
│  └─────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────┘

Security

Protections

Disabled by Default

• Diagnostics tool — must be explicitly enabled via FWSMCP_DIAGNOSTICS_ENABLED=true
• SearXNG integration — requires explicit FWSMCP_SEARXNG_URL configuration

See docs/SECURITY.md for the full threat model.

Development

git clone https://github.com/your-org/fast-web-search-mcp.git
cd fast-web-search-mcp
npm ci
npm run build
npm test

Available Scripts

Project Structure

fast-web-search-mcp/
├── src/
│   ├── cache/              # LRU cache, cache key generation
│   ├── config/             # Defaults, env parsing, config loader
│   ├── fetch/              # URL validation, content extraction, Markdown
│   ├── http/               # HTTP client, errors, headers
│   ├── observability/      # Structured stderr logger
│   ├── providers/          # DuckDuckGo, Bing, Wikipedia, SearXNG
│   ├── schemas/            # Zod validation schemas
│   ├── search/             # Orchestrator, coalescer, rate limiter, dedup
│   ├── server/             # MCP server factory, tool registration
│   ├── tools/              # 5 MCP tool implementations
│   ├── utils/              # Domain, text, date, async utilities
│   └── index.ts            # Entry point
├── test/
│   ├── fixtures/           # HTML fixtures for parser tests
│   └── unit/               # Unit tests (183 tests)
├── docs/                   # Documentation and ADRs
└── examples/               # Config examples

Documentation

Roadmap

• SQLite persistent cache
• Brave Search provider
• Image search support
• Streamable HTTP transport
• Result scoring customization

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing)
3. Commit changes (git commit -m 'feat: add amazing feature')
4. Push to branch (git push origin feature/amazing)
5. Open a Pull Request

License

MIT License. See LICENSE for details.