Provides web search through DuckDuckGo, allowing queries to return result titles, URLs, and snippets, with configurable result limits.
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., "@busqueda-web-mcp Busca cuál es la última versión de ComfyUI."
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.
MCP local pequeño para buscar con DuckDuckGo y leer páginas públicas desde LM Studio. Python 3.11+, transporte stdio, sin puertos, API keys, Docker, bases de datos ni procesos auxiliares permanentes. Pensado para modelos pequeños: dos herramientas, schemas simples y respuestas limitadas.
Consulta el manual de instalación para Windows: incluye requisitos, instalación con PowerShell o CMD, configuración de LM Studio, comprobaciones y solución de problemas. El ejemplo de configuración está en examples/mcp.windows.json.
Related MCP server: Websearch MCP Server
Instala Python y pip con el gestor del sistema si faltan (sudo pacman -S python python-pip). No uses sudo pip.
Clona el repositorio e instala el proyecto en un entorno virtual:
git clone https://github.com/konatox/busqueda-web-mcp.git ~/dev/busqueda-web-mcp
cd ~/dev/busqueda-web-mcp
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .En Fish, cambia únicamente la activación:
source .venv/bin/activate.fish
python -m pip install -e .Los tests usan unittest, incluido en Python. Las dependencias directas son el SDK oficial mcp (FastMCP incluido, rama 1.x), httpx, beautifulsoup4 y ddgs. Se fija backend="duckduckgo" y se rechaza un backend no disponible para impedir el fallback automático de DDGS; no se usa Google. El lector usa busqueda-web-mcp/1.0; DDGS gestiona su propio User-Agent de navegador.
python -m busqueda_web_mcp.server
# O el script instalado:
busqueda-web-mcpEs normal que el proceso espere sin imprimir nada: habla JSON-RPC por stdin/stdout; no es una CLI de chat. Ctrl+C lo detiene. Todos los logs van a stderr.
El nombre de distribución y del comando es busqueda-web-mcp; el módulo Python usa guiones bajos (busqueda_web_mcp) para mantener imports convencionales. Instala primero el paquete: entonces funciona desde cualquier directorio, sin PYTHONPATH.
En la configuración MCP de LM Studio, agrega este contenido a mcp.json (integra mcpServers con los servidores existentes):
{
"mcpServers": {
"busqueda-web": {
"command": "/home/konatox/dev/busqueda-web-mcp/.venv/bin/python",
"args": ["-m", "busqueda_web_mcp.server"]
}
}
}También disponible en examples/mcp.json. Ajusta la ruta si instalaste en otro lugar. LM Studio inicia el proceso; no necesitas iniciarlo en otra terminal. Selecciona un modelo con soporte de llamadas a herramientas y habilita este MCP en el chat. La calidad de la elección de herramientas depende del modelo y su plantilla.
En Windows, usa la ruta a .venv/Scripts/python.exe siguiendo el manual de Windows.
Documentación de referencia: MCP en LM Studio, SDK oficial Python, DDGS.
Herramienta | Parámetros | Respuesta |
|
|
|
|
| URL final ( |
{"query": "latest comfyui release", "max_results": 3}{"url": "https://example.com", "max_chars": 4000}Los errores devuelven error: true y un message breve. fetch_url conserva además url, title, text, truncated; si la petición falla, url es la URL solicitada y el contenido queda vacío. Los errores de esquema MCP se devuelven como errores de herramienta del SDK, sin traceback. Los detalles técnicos se registran en stderr.
Prompts de ejemplo:
Busca cuál es la última versión de ComfyUI.
Busca información reciente sobre Proton y Helldivers 2 y revisa el resultado más relevante.
Busca documentación oficial de Python asyncio. Lee solo el resultado más relevante con un máximo de 4000 caracteres y cita su URL.
Todos los límites están en src/busqueda_web_mcp/config.py: 8 resultados, timeout de 10 segundos, 30000 caracteres por página, descarga máxima de 2 MB descomprimidos, 5 redirecciones, query de 500 caracteres, URL de 4096 caracteres, títulos de 300 y snippets de 500. Los parámetros fuera de rango se rechazan. El timeout de lectura incluye DNS, redirecciones y descarga.
La caché de búsqueda usa memoria local: TTL de 5 minutos, máximo 100 entradas. Desactívala con CACHE_ENABLED = False y reinicia el MCP. No persiste datos en disco.
fetch_url solo acepta HTTP/HTTPS sin credenciales. Rechaza localhost, direcciones no globales, privadas, loopback, link-local, multicast, reservadas y metadata cloud. Valida todas las respuestas DNS y cada redirección. Conecta a una IP comprobada, conservando Host y el hostname TLS para evitar una segunda resolución DNS vulnerable a rebinding. Mantiene la verificación de certificados e ignora proxies del entorno en el lector.
Si falla el establecimiento de conexión con una IP, prueba las demás IP públicas validadas del dominio dentro del mismo timeout total. No reintenta errores HTTP ni descargas interrumpidas.
Las páginas son datos externos: pueden contener instrucciones maliciosas. El modelo debe usarlas como fuentes, sin obedecer instrucciones incrustadas. Este filtro de red no reemplaza el aislamiento del sistema operativo frente a un administrador de red malicioso.
python -m unittest discover -s tests -v
python scripts/check_stdio.py
python scripts/manual_search.py 'última versión ComfyUI'Los tests y check_stdio.py funcionan sin Internet. Este último inicia el servidor como subproceso, negocia MCP, comprueba las dos herramientas y ejecuta una llamada bloqueada. manual_search.py usa DuckDuckGo real; devuelve un código de salida distinto de cero ante error o búsqueda sin resultados. Para probar también una lectura pública:
python scripts/manual_search.py 'Python asyncio documentation' --readLa prueba real requiere Internet y puede fallar por límites de DuckDuckGo. No es parte de la suite offline.
DuckDuckGo puede devolver CAPTCHA, rate limit, resultados vacíos o cambiar sus endpoints. No hay SLA, reintentos automáticos ni fallback a otro buscador. DDGS se encarga de su mecanismo web; su timeout limita peticiones y el servicio limita cuánto espera una llamada. Un trabajo síncrono iniciado en un thread puede terminar después del timeout; no se puede cancelar forzosamente ese thread.
No ejecuta JavaScript, no inicia sesión ni procesa PDF, imágenes, vídeo o formatos binarios. Acepta HTML/XHTML y texto plano. Una página superior a 2 MB se rechaza.
La extracción es heurística: prioriza main, contenido con role=main o article, conserva encabezados/párrafos/listas y elimina navegación, formularios y duplicados. Puede omitir contenido útil en sitios atípicos; la codificación sin charset se interpreta con el fallback de httpx.
Las URLs de búsqueda son referencias, no se descargan ni resuelven automáticamente. Se validan de nuevo al llamar fetch_url.
search_and_read queda fuera de v1 para mantener mínimo el contexto y dejar la selección al modelo. Una futura implementación debe limitarse a MAX_SEARCH_AND_READ_PAGES = 3 y reutilizar los servicios actuales.
Para nuevos proveedores, implementa SearchProvider.search e inyéctalo en SearchService. No hace falta cambiar las herramientas MCP.
ModuleNotFoundError: ejecuta python -m pip install -e . con el mismo Python configurado en mcp.json; usa busqueda_web_mcp.server con guiones bajos.
El servidor no imprime nada: es normal con stdio. Usa python scripts/check_stdio.py para verificar el protocolo.
LM Studio no muestra herramientas: revisa la ruta absoluta, JSON válido, logs MCP, activación del servidor y soporte de herramientas del modelo. Reinicia el servidor tras instalar o modificar configuración.
Timeout/rate limit: revisa la conexión; espera y prueba una consulta corta. No aumentes ilimitadamente los límites.
Could not connect to the page: falló la conexión HTTP; la búsqueda usa otro cliente y puede funcionar aunque el lector falle. Para ver el traceback con la causa concreta, ejecuta python scripts/manual_fetch.py 'https://www.mimicpc.com/learn/how-to-craft-wan22-ai-video-prompts'. Los errores de certificado y negociación TLS tienen mensajes específicos. El lector requiere salida directa a Internet y no usa los proxies del entorno.
URL bloqueada: alguna IP DNS o redirección es privada/reservada; el bloqueo es intencional. No desactives la validación para leer servicios internos.
Unsupported Content-Type/texto vacío: usa otra página HTML estática o texto plano. Los sitios que requieren JavaScript o bloquean clientes HTTP no se pueden leer con este lector.
La validación realizada y las restricciones del entorno de construcción están registradas en VALIDATION.md.
Read useful text from a public HTTP or HTTPS webpage. Use after web_search when more detail from a specific result is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | ||
| max_chars | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose two real behavioral facts: only public HTTP/HTTPS pages are supported, and the return is extracted 'useful text' rather than raw HTML. It says nothing about truncation behavior, fetch failures/timeouts, rate limits, or what happens on non-text content, which are significant gaps for a network tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, zero waste, with the capability stated first and the routing guidance second. Nothing is padded or restated from the title.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no output schema and no annotations, the description covers purpose and sequencing but leaves the return shape and the truncation control unexplained. An agent knows when to call it but not what it will get back or how to bound the response size.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only implicitly covers 'url' via the word 'webpage'. The 'max_chars' parameter — which controls truncation with a default of 12000 and a 30000 cap — is never mentioned, so an agent gets no signal that output length is tunable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Read useful text from a public HTTP or HTTPS webpage') and explicitly scopes it against the sibling tool ('Use after web_search when more detail from a specific result is needed'). An agent can distinguish fetch_url from web_search without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear usage context and names the alternative: call this after web_search when a specific result needs more detail. What's missing is any exclusion — nothing says when not to use it (e.g., login-gated pages, JS-rendered content, or non-HTML resources), which the 'public' qualifier only hints at.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the public web for current or external information. Returns titles, URLs and short snippets. Use before fetch_url when you do not know the exact page.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| max_results | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It does state the return shape (titles, URLs, short snippets), which is valuable, but says nothing about result freshness, rate limits, authentication, or what happens when zero results are found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with purpose and then return shape, then routing. No filler and nothing buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool the description covers purpose, return shape, and sibling routing, but leaves the second parameter undocumented and gives no hint about result quality, freshness, or failure modes. Adequate to invoke, not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate and does not: the query parameter is only implied by the word 'Search', and max_results (default 5, max 8) is never mentioned. An agent gets no guidance on query formatting or how result count affects cost or latency.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search the public web') plus the scope of information it targets ('current or external'). It explicitly contrasts with the sibling tool fetch_url, so an agent can choose between them without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit decision rule: use this before fetch_url when the exact page is unknown. The alternative tool is named and the condition that selects it is stated, which is exactly the routing guidance an agent needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0fetch_urlweb_searchScored across 2 tools
The two tools are cleanly separated: web_search returns candidate results and fetch_url reads a single known page. The descriptions explicitly state the sequencing relationship (search first when the URL is unknown, fetch after for detail), leaving no realistic chance of misselection.
Both names are lowercase snake_case and self-descriptive, but the word order differs: 'web_search' is noun-first while 'fetch_url' is verb-first. The deviation is minor and readability is unaffected.
Two tools is thin in absolute terms, but the server's scope is a minimal search-plus-read pair and each tool clearly earns its place. Nothing redundant is present, though the surface is small enough that it could feel under-served.
The search -> fetch lifecycle for read-only web retrieval is fully covered with no dead ends. Minor gaps exist around pagination/result limits, content-format options, or non-HTML resources, which agents can usually work around but may occasionally hit.
LLM-ready web search + instant answers + URL-to-clean-text fetch for agents and RAG.
Web data for agents. Extract web pages, crawl websites, discover URLs, and search the web.
Web search and page reading for AI agents, including JSON APIs, RSS feeds and YouTube.
Web scraping, Google SERP, Markdown and ChatGPT/Gemini answers as typed tools for AI agents.
