websearch-mcp
Integrates with Ollama's OpenAI-compatible endpoints to provide LLM-based synthesis of web content and image description capabilities via vision models.
Supports using OpenAI chat and vision models for processing web search results and generating descriptions for images.
Provides web search capabilities by querying SearXNG instances, allowing for result filtering and content synthesis from search result pages.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@websearch-mcp search for the latest news about SpaceX Starship and summarize it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpTools
web_search
Search the web via SearXNG, fetch top result pages, and synthesize with LLM.
Parameter | Type | Required | Description |
| string | Yes | Search query |
| int | No | Max results (default: 10) |
| string[] | No | Only include these domains |
| string[] | No | Exclude these domains |
webfetch
Fetch a single URL, extract content, and process with LLM.
Parameter | Type | Required | Description |
| string | Yes | URL to fetch |
| 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 |
| 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 |
| Yes | — | Base URL of SearXNG instance |
| Yes | — | OpenAI-compatible endpoint base URL |
| Yes | — | API key for the LLM endpoint |
| Yes | — | Model name for chat completions |
| No |
| Cache TTL in seconds (0 to disable) |
| No |
| Max cache entries before LRU eviction |
| No |
| Per-page fetch timeout in seconds |
| No |
| LLM request timeout in seconds |
| No |
| Max content size in bytes (5MB) |
| No |
| Default result count for web_search |
VLM Configuration (for image-description tool)
Variable | Required | Default | Description |
| No |
| OpenAI-compatible endpoint for VLM |
| No |
| API key for VLM endpoint |
| No |
| Model name for image description |
| No |
| 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/ -vExample 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"
}
}
}
}Available Tools
3 toolsimage_descriptionA
Describe an image using a vision language model.
Args:
image: Either a base64-encoded string containing the image data,
or an absolute filesystem path pointing to an image file.
Returns:
JSON string with description, success status, and error info.
Inputs: image (required). Returns: result
webfetchB
Fetch a single URL, extract content, and process with LLM.
Args:
url: The URL to fetch.
prompt: Optional instruction for LLM processing. If omitted, provides a general summary.
Inputs: url (required), prompt. Returns: result
web_searchA
Search the web using SearXNG, fetch top result pages, and synthesize with LLM.
Args:
query: The search query string.
max_results: Maximum number of results to return (default: 10).
allowed_domains: Only include results from these domains.
blocked_domains: Exclude results from these domains.
Inputs: query (required), max_results, allowed_domains, blocked_domains. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose with no overlap: image_description handles visual analysis, webfetch processes single URLs, and web_search performs multi-result web searches. The boundaries are well-defined, preventing agent misselection.
Two tools follow a consistent 'web_' prefix pattern (web_search, webfetch), but image_description deviates with a different naming convention. The naming is still readable and mostly predictable, with only minor inconsistency.
Three tools is reasonable for a web search server, covering core functionalities (image analysis, URL fetching, web searches). It's slightly thin but well-scoped, with each tool earning its place without bloat.
The toolset covers key web search operations (searching, fetching, image analysis), but there are notable gaps like missing update/delete operations for saved searches or history management. Agents can work around this, but the surface is not fully comprehensive for extended workflows.
Related MCP Connectors
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.
Web scraping, search, crawling, structured extraction and research for AI agents.
Web search, browser automation, scraping, crawling and CAPTCHA solving for AI agents.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.