websearch-mcp
An MCP server that provides web search and page fetching tools for AI agents. Uses SearXNG for search, Crawl4AI for content extraction, and any OpenAI-compatible LLM for server-side synthesis.
Prerequisites
- Python 3.12+
- SearXNG instance with JSON format enabled (
search.formats: [json]insettings.yml) - OpenAI-compatible LLM endpoint (OpenAI, Ollama, vLLM, LiteLLM, etc.)
Installation
# Run directly from GitHub
uvx --from "git+https://github.com/<org>/websearch-mcp" websearch-mcp
# Or clone and install locally
git clone https://github.com/<org>/websearch-mcp
cd websearch-mcp
uv sync
uv run websearch-mcp
Tools
web_search
Search the web via SearXNG, fetch top result pages, and synthesize with LLM.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Search query |
max_results | int | No | Max results (default: 10) |
allowed_domains | string[] | No | Only include these domains |
blocked_domains | string[] | No | Exclude these domains |
webfetch
Fetch a single URL, extract content, and process with LLM.
| Parameter | Type | Required | Description |
|---|---|---|---|
url | string | Yes | URL to fetch |
prompt | string | No | Custom instruction for LLM processing |
image-description
Describe an image using a vision language model (VLM). Accepts either base64-encoded image data or an absolute filesystem path to an image file.
| Parameter | Type | Required | Description |
|---|---|---|---|
image | string | Yes | Base64-encoded image data or absolute filesystem path |
Returns a JSON object with description, success status, and optional error message.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
SEARXNG_URL | Yes | — | Base URL of SearXNG instance |
LLM_BASE_URL | Yes | — | OpenAI-compatible endpoint base URL |
LLM_API_KEY | Yes | — | API key for the LLM endpoint |
LLM_MODEL | Yes | — | Model name for chat completions |
CACHE_TTL_SECONDS | No | 900 | Cache TTL in seconds (0 to disable) |
CACHE_MAX_ENTRIES | No | 1000 | Max cache entries before LRU eviction |
FETCH_TIMEOUT | No | 30 | Per-page fetch timeout in seconds |
LLM_TIMEOUT | No | 60 | LLM request timeout in seconds |
MAX_CONTENT_SIZE | No | 5242880 | Max content size in bytes (5MB) |
DEFAULT_MAX_RESULTS | No | 10 | Default result count for web_search |
VLM Configuration (for image-description tool)
| Variable | Required | Default | Description |
|---|---|---|---|
VLM_BASE_URL | No | LLM_BASE_URL | OpenAI-compatible endpoint for VLM |
VLM_API_KEY | No | LLM_API_KEY | API key for VLM endpoint |
VLM_MODEL | No | LLM_MODEL | Model name for image description |
MAX_IMAGE_SIZE | No | 10485760 | Max image size in bytes (10MB) |
Agent Configuration
Claude Desktop (stdio)
{
"mcpServers": {
"websearch": {
"command": "uvx",
"args": ["--from", "git+https://github.com/<org>/websearch-mcp", "websearch-mcp"],
"env": {
"SEARXNG_URL": "http://localhost:8888",
"LLM_BASE_URL": "http://localhost:11434/v1",
"LLM_API_KEY": "ollama",
"LLM_MODEL": "llama3"
}
}
}
}
Generic MCP Config (stdio)
{
"command": "uvx",
"args": ["--from", "git+https://github.com/<org>/websearch-mcp", "websearch-mcp"],
"env": {
"SEARXNG_URL": "http://localhost:8888",
"LLM_BASE_URL": "https://api.openai.com/v1",
"LLM_API_KEY": "sk-...",
"LLM_MODEL": "gpt-4o-mini"
}
}
HTTP Transport
websearch-mcp --transport http --port 3000
{
"url": "http://localhost:3000/mcp"
}
Development
uv sync
uv run pytest tests/ -v
Example Usage
image-description tool
With base64-encoded image:
# Using base64 encoded image data
image_b64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
result = await image_description(image_b64)
# Returns: {"description": "A small white square", "success": true, "error": null}
With filesystem path:
# Using absolute filesystem path
result = await image_description("/path/to/image.png")
# Returns: {"description": "A detailed description of the image", "success": true, "error": null}
With Ollama (using llava or other VLM):
{
"mcpServers": {
"websearch": {
"command": "uvx",
"args": ["--from", "git+https://github.com/<org>/websearch-mcp", "websearch-mcp"],
"env": {
"SEARXNG_URL": "http://localhost:8888",
"LLM_BASE_URL": "http://localhost:11434/v1",
"LLM_API_KEY": "ollama",
"LLM_MODEL": "llama3",
"VLM_BASE_URL": "http://localhost:11434/v1",
"VLM_API_KEY": "ollama",
"VLM_MODEL": "llava"
}
}
}
}