MCP Server LogoMCP Server
MCPsCategoriesDirectorySubmit
Submit
MCPsCategoriesDirectorySubmit
Submit

MCP Servers

A curated list of MCP Servers, featuring Awesome MCP Servers and Claude MCP integration.

Contact Us

[email protected]

About

Privacy PolicyTerms of Service

Resources

Model Context ProtocolMCP Starter GuideClaude MCP Servers

Community

GitHub

© 2025 mcpserver.cc © 2025 MCP Server. All rights reserved.

Privacy PolicyTerms of Service
  1. Home
  2. /Categories
  3. /Search & Knowledge Discovery
  4. /Websearch Mcp
Websearch Mcp

Websearch Mcp

Created by mnhlt•20 days ago
Visit Website

[Self-hosted] A Model Context Protocol (MCP) server implementation that provides a web search capability over stdio transport. This server integrates with a WebSearch Crawler API to retrieve search results.

Search & Knowledge Discovery
internet-access-llmwebsearch

WebSearch-MCP

A Model Context Protocol (MCP) server implementation that provides a web search capability over stdio transport. This server integrates with a WebSearch Crawler API to retrieve search results.

Table of Contents

  • About
  • Installation
  • Configuration
  • Setup & Integration
    • Setting Up the Crawler Service
      • Prerequisites
      • Starting the Crawler Service
      • Testing the Crawler API
      • Custom Configuration
    • Integrating with MCP Clients
      • Quick Reference: MCP Configuration
      • Claude Desktop
      • Cursor IDE
      • Cline
  • Usage
    • Parameters
    • Example Search Response
    • Testing Locally
    • As a Library
  • Troubleshooting
    • Crawler Service Issues
    • MCP Server Issues
  • Development
    • Project Structure
    • Publishing to npm
  • Contributing
  • License

About

WebSearch-MCP is a Model Context Protocol server that provides web search capabilities to AI assistants that support MCP. It allows AI models like Claude to search the web in real-time, retrieving up-to-date information about any topic.

The server integrates with a Crawler API service that handles the actual web searches, and communicates with AI assistants using the standardized Model Context Protocol.

Installation

Installing via Smithery

To install WebSearch for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @mnhlt/WebSearch-MCP --client claude

Manual Installation

npm install -g websearch-mcp

Or use without installing:

npx websearch-mcp

Configuration

The WebSearch MCP server can be configured using environment variables:

  • API_URL: The URL of the WebSearch Crawler API (default: http://localhost:3001)
  • MAX_SEARCH_RESULT: Maximum number of search results to return when not specified in the request (default: 5)

Examples:

## Configure API URL
API_URL=https://crawler.example.com npx websearch-mcp

## Configure maximum search results
MAX_SEARCH_RESULT=10 npx websearch-mcp

## Configure both
API_URL=https://crawler.example.com MAX_SEARCH_RESULT=10 npx websearch-mcp

Setup & Integration

Setting up WebSearch-MCP involves two main parts: configuring the crawler service that performs the actual web searches, and integrating the MCP server with your AI client applications.

Setting Up the Crawler Service

The WebSearch MCP server requires a crawler service to perform the actual web searches. You can easily set up the crawler service using Docker Compose.

Prerequisites

  • Docker and Docker Compose

Starting the Crawler Service

  1. Create a file named docker-compose.yml with the following content:
version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:

workaround for Mac Apple Silicon

version: '3.8'

services:
  crawler:
    image: laituanmanh/websearch-crawler:latest
    container_name: websearch-api
    platform: "linux/amd64"
    restart: unless-stopped
    ports:
      - "3001:3001"
    environment:
      - NODE_ENV=production
      - PORT=3001
      - LOG_LEVEL=info
      - FLARESOLVERR_URL=http://flaresolverr:8191/v1
    depends_on:
      - flaresolverr
    volumes:
      - crawler_storage:/app/storage

  flaresolverr:
    image: 21hsmw/flaresolverr:nodriver
    platform: "linux/arm64"
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
      - TZ=UTC

volumes:
  crawler_storage:
  1. Start the services:
docker-compose up -d
  1. Verify that the services are running:
docker-compose ps
  1. Test the crawler API health endpoint:
curl http://localhost:3001/health

Expected response:

{
  "status": "ok",
  "details": {
    "status": "ok",
    "flaresolverr": true,
    "google": true,
    "message": null
  }
}

The crawler API will be available at http://localhost:3001.

Testing the Crawler API

You can test the crawler API directly using curl:

curl -X POST http://localhost:3001/crawl \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript best practices",
    "numResults": 2,
    "language": "en",
    "filters": {
      "excludeDomains": ["youtube.com"],
      "resultType": "all" 
    }
  }'

Custom Configuration

You can customize the crawler service by modifying the environment variables in the docker-compose.yml file:

  • PORT: The port on which the crawler API listens (default: 3001)
  • LOG_LEVEL: Logging level (options: debug, info, warn, error)
  • FLARESOLVERR_URL: URL of the FlareSolverr service (for bypassing Cloudflare protection)

Integrating with MCP Clients

Quick Reference: MCP Configuration

Here’s a quick reference for MCP configuration across different clients:

{
    "mcpServers": {
        "websearch": {
            "command": "npx",
            "args": [
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "5" // reduce to save your tokens, increase for wider information gain
            }
        }
    }
}

Workaround for Windows, due to Issue

{
	"mcpServers": {
	  "websearch": {
            "command": "cmd",
            "args": [
				"/c",
				"npx",
                "websearch-mcp"
            ],
            "environment": {
                "API_URL": "http://localhost:3001",
                "MAX_SEARCH_RESULT": "1"
            }
        }
	}
  }

Usage

This package implements an MCP server using stdio transport that exposes a web_search tool with the following parameters:

Parameters

  • query (required): The search query to look up
  • numResults (optional): Number of results to return (default: 5)
  • language (optional): Language code for search results (e.g., ‘en’)
  • region (optional): Region code for search results (e.g., ‘us’)
  • excludeDomains (optional): Domains to exclude from results
  • includeDomains (optional): Only include these domains in results
  • excludeTerms (optional): Terms to exclude from results
  • resultType (optional): Type of results to return (‘all’, ‘news’, or ‘blogs’)

Example Search Response

Here’s an example of a search response:

{
  "query": "machine learning trends",
  "results": [
    {
      "title": "Top Machine Learning Trends in 2025",
      "snippet": "The key machine learning trends for 2025 include multimodal AI, generative models, and quantum machine learning applications in enterprise...",
      "url": "https://example.com/machine-learning-trends-2025",
      "siteName": "AI Research Today",
      "byline": "Dr. Jane Smith"
    },
    {
      "title": "The Evolution of Machine Learning: 2020-2025",
      "snippet": "Over the past five years, machine learning has evolved from primarily supervised learning approaches to more sophisticated self-supervised and reinforcement learning paradigms...",
      "url": "https://example.com/ml-evolution",
      "siteName": "Tech Insights",
      "byline": "John Doe"
    }
  ]
}

Testing Locally

To test the WebSearch MCP server locally, you can use the included test client:

npm run test-client

This will start the MCP server and a simple command-line interface that allows you to enter search queries and see the results.

You can also configure the API_URL for the test client:

API_URL=https://crawler.example.com npm run test-client

As a Library

You can use this package programmatically:

import { createMCPClient } from '@modelcontextprotocol/sdk';

// Create an MCP client
const client = createMCPClient({
  transport: { type: 'subprocess', command: 'npx websearch-mcp' }
});

// Execute a web search
const response = await client.request({
  method: 'call_tool',
  params: {
    name: 'web_search',
    arguments: {
      query: 'your search query',
      numResults: 5,
      language: 'en'
    }
  }
});

console.log(response.result);

Troubleshooting

Crawler Service Issues

  • API Unreachable: Ensure that the crawler service is running and accessible at the configured API_URL.
  • Search Results Not Available: Check the logs of the crawler service to see if there are any errors:
    docker-compose logs crawler
    
  • FlareSolverr Issues: Some websites use Cloudflare protection. If you see errors related to this, check if FlareSolverr is working:
    docker-compose logs flaresolverr
    

MCP Server Issues

  • Import Errors: Ensure you have the latest version of the MCP SDK:
    npm install -g @modelcontextprotocol/sdk@latest
    
  • Connection Issues: Make sure the stdio transport is properly configured for your client.

Development

To work on this project:

  1. Clone the repository
  2. Install dependencies: npm install
  3. Build the project: npm run build
  4. Run in development mode: npm run dev

The server expects a WebSearch Crawler API as defined in the included swagger.json file. Make sure the API is running at the configured API_URL.

Project Structure

  • .gitignore: Specifies files that Git should ignore (node_modules, dist, logs, etc.)
  • .npmignore: Specifies files that shouldn’t be included when publishing to npm
  • package.json: Project metadata and dependencies
  • src/: Source TypeScript files
  • dist/: Compiled JavaScript files (generated when building)

Publishing to npm

To publish this package to npm:

  1. Make sure you have an npm account and are logged in (npm login)
  2. Update the version in package.json (npm version patch|minor|major)
  3. Run npm publish

The .npmignore file ensures that only the necessary files are included in the published package:

  • The compiled code in dist/
  • README.md and LICENSE files
  • package.json

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

ISC

Prerequisites

  • •Familiarity with the server domain
  • •Basic understanding of related technologies
  • •Knowledge of Search & Knowledge Discovery

Recommended Server

Logseq Mcp

Logseq Mcp

simple logseq mcp server

Mcp Llms Txt Explorer

Mcp Llms Txt Explorer

MCP to explore websites with llms.txt files

Mcp Guide

Mcp Guide

A beginner-friendly guide server that helps users understand MCP concepts, provides interactive examples, and demonstrates best practices for building MCP integrations. Features tools for exploring MCP capabilities, resources for learning core concepts, and prompts for guided tutorials.

View more → →

Details

Created

June 11, 2025

Last Updated

June 11, 2025

Category

Search & Knowledge Discovery

Author

mnhlt

Share

More Server

Mcpnotes

Mcpnotes

A simple note-taking MCP server for recording and managing notes with AI models.

Mcp

Mcp

The registry mcp server updates your resume while you code

Mcp Twitter Server

Mcp Twitter Server

Model Context Protocol Server for Accessing twitter

Ragdocs

Ragdocs

MCP server for RAG-based document search and management