home / mcp / unified search mcp server

Unified Search MCP Server

Provides unified search across Google Scholar, Google Web Search, and YouTube with security, caching, and monitoring.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "jdeun-unified-search-mcp-server": {
      "command": "python",
      "args": [
        "unified_search_server.py"
      ],
      "env": {
        "MCP_PORT": "8080",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_API_KEY",
        "YOUTUBE_API_KEY": "YOUR_YOUTUBE_API_KEY",
        "MCP_ENCRYPTION_KEY": "YOUR_256_BIT_KEY",
        "MCP_RATE_LIMIT_SECRET": "YOUR_SECRET",
        "GOOGLE_CUSTOM_SEARCH_ENGINE_ID": "YOUR_CSE_ID"
      }
    }
  }
}

Unified Search MCP Server provides a unified way to query multiple sources—Google Scholar, Google Web Search, and YouTube—through a single MCP endpoint. It combines results efficiently, supports secure handling of API keys, distributed caching, rate limiting, monitoring, and auditing to help you build scalable search experiences.

How to use

You interact with the Unified Search MCP Server by starting the local server (stdio) or by invoking it through an MCP client that communicates over the MCP protocol. Your client can request searches across all sources at once or target a single source, then aggregate and display the results in your application. You will supply your API keys for Google Custom Search and YouTube Data API, and you can rely on built-in security, caching, and monitoring features to keep usage reliable and compliant.

How to install

Prerequisites you need before installation: Python 3.11 or newer, and optionally Redis if you want distributed caching.

# 1) Clone the project
git clone https://github.com/JDeun/unified-search-mcp-server.git
cd unified-search-mcp-server

# 2) Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # on Windows: venv\Scripts\activate

# 3) Install dependencies
pip install -r requirements.txt

# 4) Copy the example environment file for customization
cp .env.example .env
# Edit .env to add API keys and settings

If you prefer a quick start without manual setup, you can run through a supported deployment method that configures the server automatically. This option is suitable for initial experimentation and testing.

Additional sections

Configuration and runtime behavior are designed to be explicit so you can deploy with confidence. You will configure API keys, security keys, Redis for caching, environment, and logging level. The server supports structured logging, health and metrics endpoints, and configurable cache TTL to balance freshness and performance.

To run the server locally in development mode, you can start the stdio-based server using Python and the main script. For production-like operation over HTTP, the server can be started with the HTTP transport option. You can also run on a custom port by exporting the MCP_PORT environment variable.

# Development: stdio transport
python unified_search_server.py

# Production-like: HTTP transport
python unified_search_server.py --transport streamable-http

# Custom port (example)
MCP_PORT=8080 python unified_search_server.py --transport streamable-http

Available tools

unified_search

Executes a combined search across all configured sources (scholar, web, youtube) and returns aggregated results.

search_google_scholar

Searches Google Scholar for academic papers with optional author and year filters.

search_google_web

Performs web searches via Google Custom Search API with language and safety options.

search_youtube

Searches YouTube for videos with duration, upload date, and sort options.

get_author_info

Fetches author information from Google Scholar when available.

clear_cache

Clears cached search results to refresh data.

get_api_usage_stats

Retrieves current API usage and limits for monitoring.