free-search-mcp

👁 License
👁 Python
👁 MCP

Un servidor del Protocolo de Contexto de Modelo (MCP) local y sin necesidad de clave API que ofrece a cualquier LLM (Claude, GPT, Ollama local, …) la capacidad de buscar en la web, obtener y limpiar páginas, y leer documentos, sin que tengas que registrarte en ninguna API de búsqueda.

Reúne las mejores ideas de varios MCP de código abierto en un único paquete de Python y añade la ergonomía para LLM y la fiabilidad que a cada uno de ellos les faltaba.

research("how does reciprocal rank fusion work", depth=3)
 ↓
# Research brief: how does reciprocal rank fusion work
_engines: duckduckgo, mojeek, startpage · sources: 3 · ~3,400 tokens_

## Sources
- [1] Reciprocal rank fusion | Elasticsearch Reference — <https://…>
- [2] Hybrid Search Scoring (RRF) | Microsoft Learn — <https://…>
- [3] RRF explained in 4 mins — Medium — <https://…>

## Documents
…full Markdown bodies of each page, ready for the LLM to read…

Una llamada de herramienta. Tres fuentes. Sin clave API. Sin el chantaje de OPENAI_API_KEY-pero-para-búsqueda.

Por qué existe esto

Los MCP de búsqueda existentes hacen bien una cosa, pero normalmente quieres todo esto:

"Optimizado para LLM" significa aquí: salida centrada en Markdown, estimaciones de tokens, truncamiento inteligente en los límites de los párrafos, docstrings de "Mejor para / No es para / Devuelve / Errores comunes" que el modelo utiliza para elegir la herramienta correcta, sugerencias de error accionables, prompts de MCP y plantillas de recursos, y una función research() de un solo paso que colapsa búsqueda→obtención→obtención→obtención en un solo turno.

"Trafilatura" significa que extraemos el contenido principal usando trafilatura, ganador del benchmark ROUGE de Bevendorff 2023 (~0.85 frente a ~0.55 para la eliminación ingenua de código repetitivo). Cada página obtenida también devuelve author, published_date y sitename de forma gratuita.

"Filtros" significa que la búsqueda/investigación acepta freshness, include_domains, exclude_domains, category (news/pdf/github/paper/forum/blog), include_text, exclude_text.

Related MCP server: TOOL4LM

Herramientas

Además de 2 prompts de MCP (Research thoroughly, Fact-check claim) y una plantilla de recurso (cache://page/{url}) para arrastrar páginas cacheadas de vuelta al contexto sin volver a obtenerlas.

Filtros (search / research)

Todas las herramientas usan por defecto format="markdown": legible, ~40% menos tokens que JSON, con procedencia y un encabezado de presupuesto de tokens. Pasa format="json" para acceso estructurado.

Anotaciones de herramientas

Cada herramienta incluye las anotaciones correctas readOnlyHint, idempotentHint y openWorldHint para que los clientes MCP puedan etiquetarlas y controlar acciones elevadas.

Motores

Conjunto predeterminado (todos fiables, sin captchas durante llamadas repetidas): duckduckgo, mojeek, startpage.

Opcionales (desafíos intermitentes para clientes headless): brave, bing, baidu.

Brave/Bing/Baidu bloquean navegadores headless después de un puñado de llamadas (CAPTCHAs PoW, páginas de "algo salió mal", envoltorios de redirección). Pasa engines=["brave"] etc. solo cuando los predeterminados no encuentren lo que necesitas.

Instalación

git clone https://github.com/ymylive/free-search-mcp.git
cd free-search-mcp
uv sync
uv run playwright install chromium

Ejecutar como servidor independiente (transporte stdio):

uv run search-mcp

Ejecutar pruebas en vivo (accede a la web real; configura la variable de entorno):

SEARCH_MCP_TEST_NETWORK=1 uv run pytest -v

Las pruebas offline se ejecutan por defecto y no tocan la red.

Conectar a Claude Desktop

Añade esto a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o el equivalente en tu plataforma:

{
 "mcpServers": {
 "search": {
 "command": "uv",
 "args": ["--directory", "/absolute/path/to/free-search-mcp", "run", "search-mcp"]
 }
 }
}

Reinicia Claude Desktop. Las siete herramientas anteriores aparecerán en el cajón de herramientas.

Conectar a otros clientes

El servidor habla MCP estándar a través de stdio. Todo lo que soporte MCP funciona:

• Claude Code (claude mcp add search uv --directory /…/free-search-mcp run search-mcp)

• Cursor / Continue / Cline (usa el fragmento JSON anterior)

• Clientes personalizados de Python / TypeScript a través del SDK oficial de MCP

Configuración

Todos los ajustes pueden ser sobrescritos por variables de entorno con el prefijo SEARCH_MCP_:

Arquitectura

 ┌─────────────────────────────────────────────────────┐
 │ FastMCP server (stdio) │
 │ tools: search / research / fetch / fetch_batch / │
 │ read_doc / cache_search / engines │
 └────────────┬────────────────────────────────────────┘
 │
 ┌────────────▼────────────┐ ┌────────────────────────┐
 │ aggregator │ │ fetcher │
 │ - parallel engines │ │ - httpx fast path │
 │ - reciprocal rank │ │ - playwright fallback │
 │ fusion │ │ - markdownify │
 │ - search cache (FTS5) │ │ - page cache (FTS5) │
 └────┬────────────────────┘ └────────────┬───────────┘
 │ │
 ┌────▼─────────────────┐ ┌──────────────▼─────────────┐
 │ engines/ │ │ browser pool │
 │ duckduckgo.py │ │ - persistent context │
 │ mojeek.py │ │ - stealth init script │
 │ startpage.py │ │ - shared cookies │
 │ brave.py (opt) │ │ - semaphore-bounded pages│
 │ bing.py (opt) │ └────────────────────────────┘
 │ baidu.py (opt) │
 └──────────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ documents/ │ │ ratelimit │
 │ pypdf, python-docx, │ │ token bucket │
 │ markdownify │ │ per engine │
 └────────────────────────────┘ └──────────────────┘

 ┌────────────────────────────┐ ┌──────────────────┐
 │ formatting │ │ research │
 │ token estimate │ │ composed │
 │ smart truncation │ │ workflow │
 │ markdown renderers │ │ │
 └────────────────────────────┘ └──────────────────┘

Patrón de adaptador de motor

Cada motor en src/search_mcp/engines/ implementa:

class Engine:
 name: str
 needs_browser: bool # Force Playwright?
 wait_selector: str | None # CSS to wait for in browser mode

 def build_url(self, query: str, max_results: int) -> str: ...
 def parse(self, html: str) -> list[SearchResult]: ...

La clase base maneja el transporte (httpx → alternativa Playwright), la limitación de tasa y el caso en que HTTP devuelve un shell de captcha en lugar de resultados (reintentos automáticos a través del navegador).

Créditos

Este proyecto se apoya en los hombros de:

• mrkrsl/web-search-mcp — estrategia de obtención inteligente httpx-luego-Playwright, cadena de respaldo multi-motor

• Aas-ee/open-webSearch — amplitud multi-motor (Bing/DDG/Baidu/Brave/Startpage)

• VincentKaufmann/noapi-google-search-mcp — patrones anti-detección (navigator.webdriver, UA, cookies), idea de caché SQLite FTS5, read_document multiformato

• nickclyde/duckduckgo-mcp-server — limitación de tasa por motor, limpieza de contenido amigable para LLM

• Mojeek — índice de búsqueda independiente que no bloquea por User-Agent

• Model Context Protocol y el SDK oficial de Python

Licencia

MIT — ver LICENSE.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• cache_searchA
• compareA
• enginesA
• extract_structuredA
• fetchA
• fetch_batchA
• read_docA
• researchA