Web Search MCP Server for use with Local LLMs

A TypeScript MCP (Model Context Protocol) server that provides comprehensive web search capabilities with multiple tools for different use cases.

Features

Multi-Engine Web Search: Tries Google Search first, and automatically falls back to DuckDuckGo if Google fails (e.g., due to bot detection or no results)
Full Page Content Extraction: Fetches and extracts complete page content from search results
Multiple Search Tools: Three specialised tools for different use cases
MCP Protocol Compliance: Implements the Model Context Protocol for seamless integration with AI assistants
TypeScript: Built with TypeScript for type safety and better development experience
CLI Executable: Can be run as a standalone CLI tool or integrated with MCP clients

How It Works

The server provides three specialised tools for different web search needs:

1. `full-web-search` (Main Tool)

When a comprehensive search is requested, the server:

Attempts to fetch results from Google Search.
If Google returns a bot detection page, fails, or returns no results, it automatically retries the search using DuckDuckGo.
Extracts and returns the full content from the top results of whichever engine succeeded.

2. `get-web-search-summaries` (Lightweight Alternative)

For quick search results without full content extraction:

Performs the same multi-engine search as full-web-search
Returns only the search result snippets/descriptions
Does not follow links to extract full page content

3. `get-single-web-page-content` (Utility Tool)

For extracting content from a specific webpage:

Takes a single URL as input
Follows the URL and extracts the main page content
Removes navigation, ads, and other non-content elements

Compatibility

This MCP server has been developed and tested with LM Studio. It has not been tested with other MCP clients.

Model Compatibility

Important: Prioritise using more recent models designated for tool use.

Older models (even those with tool use specified) may not work or may work erratically. This seems to be the case with Llama and Deepseek. Qwen3 and Gemma 3 currently have the best restults.

✅ Works well with: Qwen3
✅ Works well with: Gemma 3
✅ Works with: Llama 3.2
✅ Works with: Recent Llama 3.1 (e.g 3.1 swallow-8B)
✅ Works with: Recent Deepseek R1 (e.g 0528 works)
⚠️ May have issues with: Some versions of Llama and Deepseek R1
❌ May not work with: Older versions of Llama and Deepseek R1

Installation (Recommended)

Requirements:

Node.js 18.0.0 or higher
npm 8.0.0 or higher

Download the latest release zip file from the Releases page
Extract the zip file to a location on your system (e.g., ~/mcp-servers/web-search-mcp/)
Open a terminal in the extracted folder and run:
```
npm install
npm run build
```
This will create a node_modules folder with all required dependencies and build the project.
Configure your mcp.json to point to the extracted dist/index.js file:

{
  "mcpServers": {
    "web-search": {
      "command": "node",
      "args": ["/path/to/extracted/web-search-mcp/dist/index.js"]
    }
  }
}

Example paths:

macOS/Linux: ~/mcp-servers/web-search-mcp/dist/index.js
Windows: C:\\mcp-servers\\web-search-mcp\\dist\\index.js

Note: You must run npm install in the root of the extracted folder (not in dist/).

Troubleshooting:

If npm install fails, try updating Node.js to version 18+ and npm to version 8+
If npm run build fails, ensure you have the latest Node.js version installed
For older Node.js versions, you may need to use an older release of this project

For Development

git clone https://github.com/mrkrsl/web-search-mcp.git
cd web-search-mcp
npm install
npm run build

Development

npm run dev    # Development with hot reload
npm run build  # Build TypeScript to JavaScript
npm run lint   # Run ESLint
npm run format # Run Prettier

MCP Integration

LM Studio Configuration

Add to your mcp.json:

{
  "mcpServers": {
    "web-search": {
      "command": "node",
      "args": ["/path/to/web-search-mcp/dist/index.js"]
    }
  }
}

MCP Tools

This server provides three specialised tools for different web search needs:

1. `full-web-search` (Main Tool)

The most comprehensive web search tool that:

Takes a search query and optional number of results (1-10, default 5)
Performs a web search (tries Google, then DuckDuckGo if needed)
Fetches full page content from each result URL
Returns structured data with search results and extracted content

Example Usage:

{
  "name": "full-web-search",
  "arguments": {
    "query": "TypeScript MCP server",
    "limit": 3,
    "includeContent": true
  }
}

2. `get-web-search-summaries` (Lightweight Alternative)

A lightweight alternative for quick search results:

Takes a search query and optional number of results (1-10, default 5)
Performs the same multi-engine search as full-web-search
Returns only search result snippets/descriptions (no content extraction)
Faster and more efficient for quick research

Example Usage:

{
  "name": "get-web-search-summaries",
  "arguments": {
    "query": "TypeScript MCP server",
    "limit": 5
  }
}

3. `get-single-web-page-content` (Utility Tool)

A utility tool for extracting content from a specific webpage:

Takes a single URL as input
Follows the URL and extracts the main page content
Removes navigation, ads, and other non-content elements
Useful for getting detailed content from a known webpage

Example Usage:

{
  "name": "get-single-web-page-content",
  "arguments": {
    "url": "https://example.com/article",
    "maxContentLength": 5000
  }
}

Standalone Usage

You can also run the server directly:

# If running from source
npm start

Documentation

See API.md for complete technical details.

License

MIT License - see LICENSE for details.

Feedback

This is an open source project and we welcome feedback! If you encounter any issues or have suggestions for improvements, please:

Open an issue on GitHub
Submit a pull request
Share your experience with different models or MCP clients

Web Search MCP Server for use with Local LLMs