MCP Search Server

A Model Context Protocol (MCP) server providing web search and content extraction tools powered by Serper.dev Google Search API.

Built with FastMCP for high performance and ease of use.

Features

• 🔍 Google Web Search - Search the web with localization and time filters
• 📄 Webpage Content Extraction - Extract main text content from any URL
• 🎨 Visual UI Search Results - Rich visual presentation of search results
• 🔐 Bearer Token Authentication - Secure API access
• 🐳 Docker Ready - Easy deployment with Docker and Docker Compose
• ⚡ HTTP/2 Support - Fast, multiplexed connections

Tools

search_web

Search the web using Google.

Parameter	Type	Description
query	string	The search query string (required)
country	string	Country code for localized results (e.g., us, cz, de)
language	string	Language code for results (e.g., en, cs, de)
location	string	Geographic location (e.g., Prague, Czech Republic)
time_period	string	Time filter: qdr:h (hour), qdr:d (day), qdr:w (week), qdr:m (month), qdr:y (year)
page	int	Page number for pagination (starts at 1)

search_web_ui

Search the web using Google and display results with a visual UI. Same parameters as search_web. Show interactive buttons to extraxt of open the webpage.

extract_webpage

Extract the main text content from a webpage URL.

Parameter	Type	Description
url	string	The URL of the webpage to extract content from (required)

Setup

Prerequisites

• Serper.dev API Key (free tier available)

Docker

Using Docker Compose (Recommended)

1. Copy docker-compose.yaml to your target directory.

2. Create .env file with your configuration, see .env.example for reference.

3. Run:

   docker-compose up -d

Using Docker directly (pre-built image)

# Pull the pre-built image from Docker Hub
docker pull georgx22/websearch_mcp:latest

# Run the container (exposes port 8000)
docker run -d -p 8000:8000 --env-file .env georgx22/websearch_mcp:latest

Health Check

The server exposes a health check endpoint:

GET /health

Returns OK with status 200 when the server is healthy.

Authentication

When MCP_API_KEY is set, all requests must include the Bearer token:

Authorization: Bearer your_api_key

Testing

The project uses pytest with pytest-asyncio, pytest-cov, and respx for HTTP mocking.

Install dev dependencies

pip install -r requirements-dev.txt

Run unit tests (no API key needed)

pytest -m "not integration" --cov --cov-report=term-missing

Run integration tests (requires SERPER_API_KEY)

pytest -m integration

Coverage configuration and thresholds are defined in pyproject.toml.

CI/CD

Two PowerShell scripts in scripts/ provide a local CI/CD pipeline:

CI (scripts/ci.ps1)

Runs lint, tests, and security checks. No Docker or API keys required.

.\scripts\ci.ps1                        # Full run (install deps + all checks)
.\scripts\ci.ps1 -SkipInstall           # Skip pip install when deps are present
.\scripts\ci.ps1 -CoverageMinimum 80   # Override minimum coverage threshold

Steps: install deps, ruff lint, ruff format, unit tests + coverage, pip-audit vulnerability scan.

CD (scripts/cd.ps1)

Builds and pushes the Docker image to georgx22/websearch_mcp. Runs CI first.

.\scripts\cd.ps1 -Version 1.0.0              # Full pipeline: CI + build + push
.\scripts\cd.ps1 -Version 1.0.0 -SkipCI      # Skip CI (already passed)
.\scripts\cd.ps1 -Version 1.0.0 -SkipPush    # Build only, no push (dry-run)
.\scripts\cd.ps1 -Version 1.0.0 -Platforms ""  # Native platform only (no buildx)

Steps: CI pipeline, preflight checks, docker buildx (multi-platform), push, verify.