mnhlt/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:
Manual Installation
Or use without installing:
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:
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:
workaround for Mac Apple Silicon
2. Start the services:
3. Verify that the services are running:
4. Test the crawler API health endpoint:
Expected response:
The crawler API will be available at http://localhost:3001.
Testing the Crawler API
You can test the crawler API directly using curl:
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:
Workaround for Windows, due to Issue
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)