Web Search Integration for Claude

Overview

WebSearch-MCP is a Model Context Protocol (MCP) server implementation that provides web search capabilities to AI assistants like Claude. It integrates with a WebSearch Crawler API to retrieve real-time search results, enabling AI models to access up-to-date information on any topic.

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 (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 the Crawler Service

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

Prerequisites

• Docker
• Docker Compose

Starting the Crawler Service

1. Create a docker-compose.yml file:

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:

1. Start the services:

docker-compose up -d

1. Verify the services:

docker-compose ps

1. Test the crawler API:

curl http://localhost:3001/health

Integrating with MCP Clients

Quick Reference: MCP Configuration

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

Usage

Parameters

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

Example 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"
    }
  ]
}

Testing Locally

npm run test-client

As a Library

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

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

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 the crawler service is running.
• Search Results Not Available: Check logs:

docker-compose logs crawler

MCP Server Issues

• Import Errors: Update the MCP SDK:

npm install -g @modelcontextprotocol/sdk@latest

Development

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

Project Structure

• .gitignore: Files ignored by Git.
• .npmignore: Files excluded from npm.
• package.json: Project metadata.
• src/: Source TypeScript files.
• dist/: Compiled JavaScript files.

Publishing to npm

1. Log in to npm: npm login.
2. Update version: npm version patch|minor|major.
3. Publish: npm publish.

Contributing

Contributions are welcome! Submit a Pull Request.

License

ISC