Mcpwebsearch

🚀 MCP Web Search Server

A privacy‑focused web, social media, and archive search server exposing tools via the Model Control Protocol (MCP) for controlled access to external search capabilities.

🚀 Quick Start

The MCP Web Search Server is a privacy - focused search server that offers access to external search capabilities through the Model Control Protocol (MCP). Here's how you can get started quickly:

# Clone the repository (if applicable)
git clone https://github.com/undici77/MCPWebSearch.git
cd MCPWebSearch

# Run the startup script (adjust name if different)
./run.sh -d /path/to/working/directory

1. Create & activate a Python virtual environment (.venv).
2. Install all required dependencies from requirements.txt.
3. Launch the MCP Search Server (main.py) which listens on stdin/stdout for JSON‑RPC messages.

📌 Ensure the startup script is executable: chmod +x run.sh

✨ Features

• Parallel search: Conduct parallel searches across multiple privacy‑focused web engines.
• Social media lookup: Perform lookups for public content on major social media platforms.
• Archive retrieval: Retrieve archived content from Wayback Machine, archive.today, Google Cache and other services.
• Dynamic listing: Dynamically list supported engines and archive services.
• Result caching: Use LRU eviction to cache results and speed up repeated queries.

📦 Installation

# Clone the repository
git clone https://github.com/undici77/MCPWebSearch.git
cd MCPWebSearch

# Run the startup script
./run.sh -d /path/to/working/directory

1. Create and activate a Python virtual environment (.venv).
2. Install all required dependencies from requirements.txt.
3. Launch the MCP Search Server (main.py) which listens for JSON - RPC messages on stdin/stdout.

📌 Make sure the startup script is executable: chmod +x run.sh

⚙️ Command‑Line Options

The server itself does not require additional CLI flags; all configuration is performed via JSON‑RPC.

💻 Integration with LM Studio

Add the following entry to your mcp.json so LM Studio can start the server automatically:

{
  "mcpServers": {
    "web-search": {
      "command": "/absolute/path/to/run.sh",
      "args": [
        "-d",
        "/absolute/path/to/working/directory"
      ],
      "env": { "WORKING_DIR": "." }
    }
  }
}

📌 Make the script executable (chmod +x /absolute/path/to/run.sh) and run ./run.sh once to install the virtual environment before launching LM Studio.

📚 MCP API Overview

All communication follows JSON‑RPC 2.0 over stdin/stdout.

initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {}
}

Response: protocol version (2024 - 11 - 05), server capabilities (tool enumeration) and basic server info (name, version).

tools/list

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list",
  "params": {}
}

Response: an array of tool definitions (name, description, input schema).

tools/call

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "<tool_name>",
    "arguments": { … }
  }
}

Note: The tool identifier key is name, not tool.

🛠️ Available Tools

web_search

Search the web using multiple privacy‑focused engines in parallel.

Example

{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "web_search",
    "arguments": {
      "query": "privacy focused search engines",
      "engine": "duckduckgo",
      "max_results": 15
    }
  }
}

The server returns a formatted text block containing titles, URLs and snippets from each selected engine.

social_search

Search public content on major social‑media platforms.

Example

{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "social_search",
    "arguments": {
      "query": "AI ethics research",
      "platform": "reddit"
    }
  }
}

The response contains direct URLs that can be opened in a browser.

archives_search

Find archived versions of a URL across multiple web‑archive services.

Example

{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "archives_search",
    "arguments": {
      "url": "https://example.com",
      "service": "wayback",
      "check_availability": true
    }
  }
}

The response lists archive URLs and, if requested, snapshot counts and timestamps.

list_engines

List all available privacy‑focused search engines.

Example

{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "list_engines",
    "arguments": {}
  }
}

The server returns a markdown‑formatted overview of each engine and usage notes.

list_archives_services

List all supported web‑archive services.

Example

{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "list_archives_services",
    "arguments": {}
  }
}

The response includes a description of each service, its ID and key features.

clear_cache

Clear the internal search‑result cache.

Example

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "clear_cache",
    "arguments": {}
  }
}

The server replies with a confirmation message.

🔧 Technical Details

Security Features

• Query sanitisation: Strips control characters, removes HTML tags and enforces MAX_QUERY_LENGTH (500).
• Strict URL validation: Accepts only http:// or https:// schemes with a valid domain.
• Blocked patterns: Uses regexes to prevent <script> injection, javascript: URIs and event - handler attributes.
• Input schema enforcement: Each tool validates required fields via the JSON‑RPC inputSchema.
• Rate limiting: An asyncio semaphore caps concurrent external requests (MAX_CONCURRENT_SEARCHES).

📄 License

© 2025 Undici77 – All rights reserved.