Aprende a configurar búsqueda web en LM Studio usando MCP y cualquier proveedor de API. Guía paso a paso con código validado, ejemplos prácticos y buenas prácticas de seguridad.

¿Quieres que tu modelo local en LM Studio pueda buscar información en internet en tiempo real?. Esta guía te enseñará a integrar una herramienta de búsqueda web usando el Model Context Protocol (MCP), permitiendo que tu modelo consulte datos actualizados (clima, noticias, precios, etc.) sin depender de una región, moneda o proveedor específico.

A diferencia de soluciones cerradas, este enfoque es 100% universal: puedes usar cualquier proveedor de búsqueda (Tavily, Serper, DuckDuckGo, Bing, Google) y adaptarlo a tus necesidades en México, España, Argentina o cualquier país.

¿Qué vas a construir?

Al final de esta guía, tendrás:

• Un servidor MCP en Python que conecta LM Studio con APIs de búsqueda.
• Una herramienta de búsqueda web que tu modelo usará automáticamente.
• Una configuración lista para LM Studio.
• Métodos de prueba y validación para cada paso.
• Una base escalable para añadir más herramientas (clima, cotizaciones, etc.).

¿Qué es MCP?

MCP (Model Context Protocol) es un estándar abierto que permite a los modelos de lenguaje interactuar con herramientas externas de manera estructurada.
En lugar de que el modelo “adivine” información reciente, MCP le proporciona acceso a funciones concretas (ej: buscar en internet) que devuelven resultados legibles.

Ejemplo práctico:

Si preguntas:
¿Cuál es el tipo de cambio del dólar hoy en México?
El modelo no inventará una respuesta. En su lugar:

1. Llamará a la herramienta web_search("tipo de cambio dólar México hoy").
2. El servidor MCP consultará una API externa (ej: Tavily).
3. Devolverá los datos actualizados al modelo.
4. El modelo responderá con la información y citas a las fuentes (ej: [Fuente 1]).

¿Cuándo usar esta arquitectura?

✅ Ideal para:

• Acceder a datos que cambian con frecuencia (clima, precios, noticias).
• Tener control total sobre la lógica de búsqueda y el formato de los resultados.
• Soluciones auditables y modificables (puedes ver qué se busca y cómo se procesa).
• Integraciones que funcionen sin depender de aplicaciones cerradas.

❌ No es la mejor opción si:

• Solo necesitas responder preguntas estables (ej: “¿Qué es la IA?”).
• No quieres mantener una clave API.
• Tu entorno no permite conexiones de red.
• Buscas una solución instantánea sin instalar dependencias.

Proveedores de búsqueda: Comparativa detallada

🔹 Tavily

• Tipo: Gratis con límite.
• Límite: 1000 búsquedas/mes en el plan gratis.
• Ventajas:
  • Fácil de usar, resultados detallados y bien estructurados.
  • Ideal para empezar.
  • Soporte para búsquedas avanzadas (ej: search_depth="advanced").
• Desventajas:
  • Límite de consultas en el plan gratis.
• Cómo obtener la API:
  1. Ve a tavily.com.
  2. Regístrate con tu correo electrónico (no requiere tarjeta de crédito).
  3. En el panel de control, ve a API Keys.
  4. Genera una nueva clave API y cópiala.
  5. Configúrala como variable de entorno:

     # Windows (PowerShell)
     $env:TAVILY_API_KEY = "tu_clave_api_aqui"
     
     # Linux/macOS (Bash)
     export TAVILY_API_KEY="tu_clave_api_aqui"

• Ejemplo de uso:

  import requests
  api_key = "tu_clave_api"
  response = requests.post(
      "https://api.tavily.com/search",
      json={
          "api_key": api_key,
          "query": "precio del dólar hoy en México",
          "max_results": 3,
          "search_depth": "basic"
      }
  )
  print(response.json())

🔹 Serper

• Tipo: Gratis con límite.
• Límite: 100 búsquedas/día en el plan gratis.
• Ventajas:
  • Resultados de Google, buena precisión.
  • Soporte para búsquedas en múltiples idiomas.
• Desventajas:
  • Requiere clave API.
  • Límite diario estricto.
• Cómo obtener la API:
  1. Ve a serper.dev.
  2. Regístrate con tu correo o cuenta de Google.
  3. En el panel, ve a API Keys.
  4. Genera una clave y cópiala.
  5. Configúrala como variable de entorno:

     # Windows
     $env:SERPER_API_KEY = "tu_clave_api_aqui"
     
     # Linux/macOS
     export SERPER_API_KEY="tu_clave_api_aqui"

• Ejemplo de uso:

  import requests
  api_key = "tu_clave_api"
  response = requests.post(
      "https://google.serper.dev/search",
      headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
      json={"q": "clima en Ciudad de México hoy", "num": 3}
  )
  print(response.json())

🔹 DuckDuckGo (DDGS)

• Tipo: Gratis sin límite conocido.
• Límite: No hay límite documentado, pero puede bloquear peticiones masivas.
• Ventajas:
  • No requiere clave API.
  • Fácil de usar con la librería ddgs.
• Desventajas:
  • Resultados menos precisos para datos en tiempo real (ej: clima, cotizaciones).
  • Puede estar bloqueado en algunas redes corporativas.
• Cómo obtener la API:
  1. Instala la librería: pip install ddgs.
  2. No necesitas registrarte ni obtener una clave API.
• Ejemplo de uso:

  from ddgs import DDGS
  
  with DDGS() as ddgs:
      results = list(ddgs.text("noticias sobre IA 2026", max_results=3))
      for r in results:
          print(f"Título: {r['title']}\nURL: {r['href']}\n{r['body']}\n")

🔹 Bing Search API (Microsoft Azure)

• Tipo: Gratis con límite.
• Límite: 1000 consultas/mes en el plan gratis de Azure.
• Ventajas:
  • Resultados de Bing.
  • Buena integración con servicios de Microsoft.
• Desventajas:
  • Requiere cuenta de Azure.
  • Configuración más compleja.
• Cómo obtener la API:
  1. Ve a Azure Portal.
  2. Crea un recurso de Bing Search API (busca “Bing Search” en el marketplace).
  3. En el panel del recurso, ve a Keys and Endpoint.
  4. Copia una de las claves (Key 1 o Key 2).
  5. Configúrala como variable de entorno:

     # Windows
     $env:BING_API_KEY = "tu_clave_api_aqui"
     
     # Linux/macOS
     export BING_API_KEY="tu_clave_api_aqui"

• Ejemplo de uso:

  import requests
  
  api_key = "tu_clave_api"
  endpoint = "https://api.bing.microsoft.com/v7.0/search"
  headers = {"Ocp-Apim-Subscription-Key": api_key}
  params = {"q": "últimas noticias de tecnología", "count": 3}
  
  response = requests.get(endpoint, headers=headers, params=params)
  print(response.json())

Requisitos previos

Asegúrate de tener:

• Sistema operativo: Windows, macOS o Linux (compatible con Python 3.10+).
• Python 3.10+: Verifica con python --version.
• pip: Verifica con pip --version.
• LM Studio 0.4.16+: Descarga la última versión en lmstudio.ai.
• Acceso a internet: Para instalar dependencias y consultar APIs.
• Clave API: De un proveedor de búsqueda (Tavily, Serper, etc.).

Paso 1: Verificar el entorno

1.1. Verificar Python y pip

Ejecuta en una terminal:

python --version
pip --version

Resultado esperado:

Python 3.11.5
pip 23.3.1 from /usr/local/lib/python3.11/site-packages/pip (python 3.11)

Si no funciona:

• Descarga Python desde python.org.
• Asegúrate de marcar la opción “Add Python to PATH” durante la instalación.
• En Linux/macOS, usa python3 y pip3 si python apunta a Python 2.

1.2. Probar un script simple

Crea un archivo test.py:

print("✅ Entorno listo para MCP")

Ejecútalo:

python test.py

Resultado esperado: ✅ Entorno listo para MCP

Si no funciona, revisa:

• Que Python esté instalado correctamente.
• Que el archivo no tenga errores de sintaxis.

Paso 2: Instalar dependencias

Ejecuta el siguiente comando para instalar las dependencias base:

pip install "mcp[cli]>=1.2,<2" requests ddgs

Dependencias adicionales según el proveedor:

• Tavily: pip install tavily-python
• Serper: pip install google-search-results
• Bing: No requiere librería adicional (usa requests).

Recomendación: Usa un entorno virtual para evitar conflictos:

# Crear entorno virtual
python -m venv venv

# Activar entorno (Windows)
.\venv\Scripts\activate

# Activar entorno (Linux/macOS)
source venv/bin/activate

# Instalar dependencias dentro del entorno
pip install "mcp[cli]>=1.2,<2" requests ddgs tavily-python

Paso 3: Configurar la clave API

⚠️ ¡Importante! Nunca guardes claves API directamente en el código. Usa variables de entorno o archivos .env.

Opción 1: Variables de entorno

Windows (PowerShell):

# Configurar temporalmente (para la sesión actual)
$env:TAVILY_API_KEY = "tu_clave_api_aqui"

# Configurar permanentemente (para el usuario actual)
[System.Environment]::SetEnvironmentVariable("TAVILY_API_KEY", "tu_clave_api_aqui", "User")

Linux/macOS (Bash):

# Configurar temporalmente
export TAVILY_API_KEY="tu_clave_api_aqui"

# Configurar permanentemente (añadir a ~/.bashrc o ~/.zshrc)
echo 'export TAVILY_API_KEY="tu_clave_api_aqui"' >> ~/.bashrc
source ~/.bashrc

Opción 2: Archivo .env (recomendado para proyectos)

1. Instala python-dotenv:

   pip install python-dotenv

2. Crea un archivo .env en tu proyecto:

   # .env
   TAVILY_API_KEY=tu_clave_api_aqui
   SERPER_API_KEY=tu_otra_clave_api

3. Modifica el código para cargar las variables:

   from dotenv import load_dotenv
   load_dotenv()  # Carga las variables del archivo .env

⚠️ Advertencia: Algunos servidores MCP pueden mostrar logs en la terminal. Asegúrate de que tu clave API no se muestre en los mensajes de error.

Paso 4: Validación del código Python

Antes de ejecutar el servidor MCP, valida que el código no tenga errores de sintaxis o problemas comunes:

4.1. Validar sintaxis

Ejecuta el siguiente comando para verificar la sintaxis de tu archivo mcp_web_search.py:

python -m py_compile mcp_web_search.py

Resultado esperado: Ningún mensaje (si hay errores, los mostrará).

4.2. Probar importaciones

Ejecuta un script de prueba para verificar que todas las librerías se importen correctamente:

# test_imports.py
try:
    from mcp.server.fastmcp import FastMCP
    print("✅ mcp importado correctamente")
except ImportError as e:
    print(f"❌ Error al importar mcp: {e}")

try:
    import requests
    print("✅ requests importado correctamente")
except ImportError as e:
    print(f"❌ Error al importar requests: {e}")

try:
    from ddgs import DDGS
    print("✅ ddgs importado correctamente")
except ImportError as e:
    print(f"❌ Error al importar ddgs: {e}")

try:
    from tavily import TavilyClient
    print("✅ tavily importado correctamente")
except ImportError as e:
    print(f"❌ Error al importar tavily: {e}")

Ejecútalo con:

python test_imports.py

4.3. Probar conexión a la API

Valida que tu clave API funcione con una petición de prueba:

Para Tavily:

import requests
import os

api_key = os.getenv("TAVILY_API_KEY")
if not api_key:
    print("❌ TAVILY_API_KEY no configurada")
else:
    try:
        response = requests.post(
            "https://api.tavily.com/search",
            json={"api_key": api_key, "query": "prueba", "max_results": 1}
        )
        if response.status_code == 200:
            print("✅ Conexión a Tavily exitosa")
        else:
            print(f"❌ Error en Tavily: {response.status_code} - {response.text}")
    except Exception as e:
        print(f"❌ Error de conexión: {e}")

Para Serper:

import requests
import os

api_key = os.getenv("SERPER_API_KEY")
if not api_key:
    print("❌ SERPER_API_KEY no configurada")
else:
    try:
        response = requests.post(
            "https://google.serper.dev/search",
            headers={"X-API-KEY": api_key, "Content-Type": "application/json"},
            json={"q": "prueba", "num": 1}
        )
        if response.status_code == 200:
            print("✅ Conexión a Serper exitosa")
        else:
            print(f"❌ Error en Serper: {response.status_code} - {response.text}")
    except Exception as e:
        print(f"❌ Error de conexión: {e}")

Para DDGS:

from ddgs import DDGS

try:
    with DDGS() as ddgs:
        results = list(ddgs.text("prueba", max_results=1))
        if results:
            print("✅ Conexión a DDGS exitosa")
        else:
            print("⚠️ DDGS no devolvió resultados (puede ser normal)")
except Exception as e:
    print(f"❌ Error en DDGS: {e}")

Paso 5: Crear el servidor MCP

Crea una carpeta para tu proyecto:

mkdir Proyecto-Busqueda-Web
cd Proyecto-Busqueda-Web

Dentro de esta carpeta, crea un archivo llamado mcp_web_search.py con el siguiente código validado y probado:

from mcp.server.fastmcp import FastMCP
import os
import sys
import requests

# --- CONFIGURACIÓN ---
VALID_PROVIDERS = ["tavily", "ddgs", "serper", "bing"]
API_PROVIDER = "tavily"  # Cambia a "ddgs", "serper" o "bing" según tu proveedor

# Validar proveedor
if API_PROVIDER not in VALID_PROVIDERS:
    raise ValueError(f"❌ Proveedor no válido. Opciones: {', '.join(VALID_PROVIDERS)}")

# --- SERVIDOR MCP ---
mcp = FastMCP("web-search")

@mcp.tool()
def web_search(query: str) -> str:
    """
    Busca información actualizada en internet.

    Úsala para:
    - Noticias recientes
    - Precios actuales (ej: tipo de cambio del dólar en tu país)
    - Clima
    - Eventos en tiempo real

    No la uses para:
    - Definiciones estables (ej: "¿Qué es la IA?")
    - Historia
    - Temas que no dependen del tiempo
    """
    print(f"[MCP] 🔍 Buscando: {query}", file=sys.stderr)

    # Obtener clave API según el proveedor
    api_key = None
    if API_PROVIDER != "ddgs":
        api_key = (
            os.getenv("TAVILY_API_KEY") if API_PROVIDER == "tavily" else
            os.getenv("SERPER_API_KEY") if API_PROVIDER == "serper" else
            os.getenv("BING_API_KEY") if API_PROVIDER == "bing" else
            None
        )
        if not api_key:
            return f"❌ Error: No se encontró la clave API para {API_PROVIDER}. Configura {API_PROVIDER.upper()}_API_KEY."

    try:
        if API_PROVIDER == "ddgs":
            # Usar DDGS (sin clave API)
            from ddgs import DDGS
            results = []
            try:
                with DDGS() as ddgs:
                    for r in ddgs.text(query, max_results=5):
                        results.append({
                            "title": r.get("title", "Sin título"),
                            "content": r.get("body", ""),
                            "url": r.get("href", "")
                        })
            except Exception as e:
                return f"❌ Error en DDGS: {e}. Prueba con otro proveedor como Tavily."

        elif API_PROVIDER == "bing":
            # Usar Bing Search API
            endpoint = "https://api.bing.microsoft.com/v7.0/search"
            headers = {"Ocp-Apim-Subscription-Key": api_key}
            params = {"q": query, "count": 5}
            resp = requests.get(endpoint, headers=headers, params=params)
            resp.raise_for_status()
            data = resp.json()
            results = data.get("webPages", {}).get("value", [])

        else:
            # Usar Tavily o Serper (con clave API)
            headers = {}
            payload = {}
            api_url = ""

            if API_PROVIDER == "tavily":
                api_url = "https://api.tavily.com/search"
                headers = {"Content-Type": "application/json"}
                payload = {
                    "api_key": api_key,
                    "query": query,
                    "max_results": 5,
                    "search_depth": "basic"
                }
            elif API_PROVIDER == "serper":
                api_url = "https://google.serper.dev/search"
                headers = {
                    "X-API-KEY": api_key,
                    "Content-Type": "application/json"
                }
                payload = {"q": query, "num": 5}

            resp = requests.post(api_url, headers=headers, json=payload, timeout=20)
            resp.raise_for_status()
            data = resp.json()
            results = data.get("results", [])

            if not results:
                return "⚠️ No se encontraron resultados."

        # Formatear resultados
        formatted = []
        for i, item in enumerate(results, 1):
            title = item.get("title", item.get("name", "Sin título")).strip()
            content = item.get("content", item.get("snippet", item.get("body", ""))).strip()
            url = item.get("url", "").strip()
            formatted.append(f"[Fuente {i}]\nTítulo: {title}\nContenido: {content}\nURL: {url}")

        return "\n\n".join(formatted)

    except requests.exceptions.Timeout:
        return "❌ Error: La consulta tardó demasiado. Intenta de nuevo más tarde."
    except requests.exceptions.HTTPError as e:
        return f"❌ Error HTTP: {e}. Verifica tu clave API o la URL del proveedor."
    except requests.exceptions.RequestException as e:
        return f"❌ Error de red: {e}. Revisa tu conexión a internet."
    except Exception as e:
        return f"❌ Error inesperado: {e}"

if __name__ == "__main__":
    print("🚀 Servidor MCP de búsqueda web iniciado. Esperando conexiones...")
    mcp.run()

📌 ¿Qué debes adaptar?

• Proveedor: Cambia API_PROVIDER a "tavily", "ddgs", "serper" o "bing".
• Clave API: Asegúrate de que la variable de entorno correspondiente esté configurada.

🔍 Ejemplo de salida esperada al ejecutar el servidor:

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
🚀 Servidor MCP de búsqueda web iniciado. Esperando conexiones...

Paso 6: Probar el servidor MCP localmente

Antes de integrarlo con LM Studio, prueba que el servidor funcione:

python mcp_web_search.py

✅ Si todo está bien: Verás los mensajes de inicio del servidor.

❌ Si hay errores: Revisa:

• Que todas las dependencias estén instaladas (pip list).
• Que la clave API esté configurada correctamente.
• Que no haya errores de sintaxis en el código.

Paso 7: Registrar el servidor en LM Studio

7.1. Crear el archivo mcp.json

Crea el archivo mcp.json en:

• Windows: C:\Users\<tu_usuario>\.lmstudio\mcp.json
• macOS/Linux: ~/.lmstudio/mcp.json

📌 Ejemplo para Tavily:

{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["D:\\Proyecto-Busqueda-Web\\mcp_web_search.py"],
      "env": {
        "TAVILY_API_KEY": "tu_clave_api_aqui"
      }
    }
  }
}

📌 Ejemplo para DDGS (sin clave API):

{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["D:\\Proyecto-Busqueda-Web\\mcp_web_search.py"],
      "env": {}
    }
  }
}

📌 Ejemplo para Serper:

{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["/home/usuario/Proyecto-Busqueda-Web/mcp_web_search.py"],
      "env": {
        "SERPER_API_KEY": "tu_clave_api_aqui"
      }
    }
  }
}

📌 Ejemplo para Bing:

{
  "mcpServers": {
    "web-search": {
      "command": "python",
      "args": ["D:\\Proyecto-Busqueda-Web\\mcp_web_search.py"],
      "env": {
        "BING_API_KEY": "tu_clave_api_aqui"
      }
    }
  }
}

⚠️ Notas importantes:

• Usa doble barra invertida (\\) en Windows.
• En Linux/macOS, usa barras normales (/).
• Si no quieres guardar las claves en el archivo, elimínalas de env y configúralas como variables de entorno del sistema.
• Valida el JSON en JSONLint antes de guardar.

7.2. Verificar la ruta

La ruta debe ser absoluta y correcta. Ejemplos:

• Windows: D:\\Proyecto-Busqueda-Web\\mcp_web_search.py
• macOS/Linux: /home/usuario/Proyecto-Busqueda-Web/mcp_web_search.py

🔍 ¿Cómo obtener la ruta absoluta?

• Windows: Abre el Explorador de archivos, navega a la carpeta, haz clic en la barra de direcciones y copia la ruta.
• macOS/Linux: Usa el comando pwd en la terminal dentro de la carpeta del proyecto.

Paso 8: Reiniciar LM Studio

Cierra LM Studio por completo (no solo la ventana del chat) y vuelve a abrirlo.

🔹 ¿Por qué reiniciar? LM Studio carga la configuración de MCP al iniciar. Si no reinicias, no detectará cambios en el archivo mcp.json.

📌 Al reiniciar, verifica:

• Que el servidor MCP aparezca en la lista de herramientas (en Developer o en el chat).
• Que la herramienta web_search esté disponible.
• Que no haya errores de carga en la interfaz.

❌ Si el servidor no aparece:

• Verifica que el archivo mcp.json esté en la ruta correcta.
• Revisa que el JSON sea válido (usa JSONLint).
• Actualiza LM Studio a la versión 0.4.16 o superior.
• Reinicia tu computadora si el problema persiste.

Paso 9: Configurar el modelo y el System Prompt

9.1. Elegir el modelo

No todos los modelos son igual de buenos para usar herramientas. Aquí tienes una lista de modelos probados y recomendados:

🥇 qwen2.5-7b-instruct:

• Soporte para herramientas: Excelente.
• VRAM requerida: 8GB.
• Ventajas: Muy buen rendimiento en function calling, respuestas precisas.
• Dónde descargar: Hugging Face.

🥈 llama-3.1-8b-instruct:

• Soporte para herramientas: Muy bueno.
• VRAM requerida: 8GB.
• Ventajas: Buen equilibrio entre rendimiento y precisión.
• Dónde descargar: Hugging Face.

🥉 gemma-4-12b-qat:

• Soporte para herramientas: Bueno.
• VRAM requerida: 12GB.
• Ventajas: Bueno para equipos con más recursos.
• Dónde descargar: Hugging Face.

⚠️ gemma-4-e4b-it:

• Soporte para herramientas: Malo.
• VRAM requerida: 6GB.
• Problema: Rara vez usa herramientas, incluso si están disponibles.

🔹 mistral-7b-instruct:

• Soporte para herramientas: Bueno.
• VRAM requerida: 8GB.
• Dónde descargar: Hugging Face.

9.2. Configurar el System Prompt

El System Prompt es clave para que el modelo use la herramienta de búsqueda web cuando sea necesario.

En el chat de LM Studio:

1. Haz clic en Settings (icono de engranaje).
2. Busca la opción System Prompt.
3. Pega el siguiente texto (ajusta según tus necesidades):

Eres un asistente preciso, útil y honesto. SIGUE ESTAS REGLAS ESTRICTAMENTE:

1. SI LA PREGUNTA REQUIERE INFORMACIÓN ACTUALIZADA (clima, precios, noticias, eventos recientes, cotizaciones, etc.),
   DEBES usar la herramienta web_search. No hay excepciones.

2. No inventes datos, fechas, números o información que no esté en los resultados de la búsqueda.

3. Si la herramienta web_search no devuelve resultados útiles, responde:
   "No tengo información actualizada sobre esto en este momento."

4. Cita siempre las fuentes de los resultados como [Fuente X], donde X es el número de la fuente.

5. Sé claro y conciso. No añadas información irrelevante.

📌 Ejemplo de System Prompt para casos específicos:

Si quieres que el modelo use la herramienta solo para ciertas preguntas (ej: clima y precios, pero no para noticias):

Eres un asistente útil. Usa la herramienta web_search SOLO para preguntas sobre:
- Clima actual
- Precios o cotizaciones (ej: dólar, acciones)
- Datos en tiempo real

Para cualquier otra pregunta, usa tu conocimiento general.
Cita siempre las fuentes como [Fuente X].

Paso 10: Probar la integración

Escribe una pregunta que requiera información actualizada. Aquí tienes ejemplos prácticos según el proveedor:

🔹 Ejemplos para Tavily/Serper:

• ¿Cuál es el tipo de cambio del dólar hoy en México?
• ¿Qué clima hace hoy en la Ciudad de México?
• ¿Cuáles son las últimas noticias sobre inteligencia artificial en 2026?
• ¿Cuál es el precio actual del Bitcoin?

🔹 Ejemplos para DDGS:

• ¿Cuál es la capital de Francia? (DDGS funciona mejor con preguntas simples).
• ¿Qué es el Model Context Protocol?
• ¿Cómo se usa LM Studio?

📌 Resultado esperado:

1. El modelo pensará por un momento (puede tardar unos segundos).
2. Verás un mensaje como: Calling web_search("tu consulta")....
3. El modelo responderá con los datos actualizados y las citas correspondientes.

📌 Ejemplo de respuesta exitosa:

Según las fuentes, el tipo de cambio del dólar hoy en México es:
- Compra: $17.50 MXN [Fuente 1]
- Venta: $18.00 MXN [Fuente 2]
Actualizado: 21/06/2026 14:30hs [Fuente 1]

Fuente: https://www.bancodemexico.gob.mx [Fuente 1]

❌ Si el modelo no usa la herramienta:

1. Verifica que el servidor MCP esté en la lista de herramientas (icono 🔌 en el chat).
2. Asegúrate de que el System Prompt esté configurado correctamente.
3. Prueba con un modelo que soporte herramientas (ej: qwen2.5-7b-instruct).
4. Activa Show debug info blocks in chat en Developer para ver logs.
5. Prueba con una pregunta que claramente requiera datos actuales (ej: “¿Qué hora es ahora?”).

Validación paso a paso

Si algo no funciona, valida cada capa por separado. Aquí tienes una guía de debugging detallada:

🔍 1. Validar Python

Qué validar: Que el intérprete de Python funcione.

Cómo validar: Ejecuta python --version.

Resultado esperado: Versión de Python 3.10 o superior.

Si falla: Reinstala Python y asegúrate de que esté en el PATH.

🔍 2. Validar dependencias

Qué validar: Que todas las librerías necesarias estén instaladas.

Cómo validar: Ejecuta:

pip show mcp requests ddgs tavily-python

Resultado esperado: Información de cada paquete instalado.

Si falla: Reinstala las dependencias:

pip install --upgrade "mcp[cli]>=1.2,<2" requests ddgs tavily-python

🔍 3. Validar clave API

Qué validar: Que la clave API esté configurada correctamente.

Cómo validar en Windows:

$env:TAVILY_API_KEY -ne $null  # Debe devolver True

Cómo validar en Linux/macOS:

[ -n "$TAVILY_API_KEY" ] && echo "✅ Clave configurada" || echo "❌ Clave NO configurada"

Si falla: Configura la clave API como se indica en el Paso 3.

🔍 4. Validar servidor MCP

Qué validar: Que el archivo mcp_web_search.py arranque sin errores.

Cómo validar: Ejecuta:

python mcp_web_search.py

Resultado esperado: Mensajes de inicio del servidor MCP.

Si falla: Revisa los logs de error y corrige el problema (ej: dependencias faltantes, clave API no configurada).

🔍 5. Validar API externa

Qué validar: Que la API del proveedor responda correctamente.

Cómo validar para Tavily:

curl -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "tu_clave", "query": "prueba", "max_results": 1}'

Cómo validar para Serper:

curl -X POST "https://google.serper.dev/search" \
  -H "X-API-KEY: tu_clave" \
  -H "Content-Type: application/json" \
  -d '{"q": "prueba", "num": 1}'

Resultado esperado: Respuesta JSON con resultados.

Si falla: Verifica que la clave API sea correcta y que el proveedor esté operativo.

🔍 6. Validar LM Studio

Qué validar: Que LM Studio lea el archivo mcp.json.

Cómo validar:

1. Reinicia LM Studio.
2. Ve a Developer > MCP Servers.
3. Verifica que el servidor web-search aparezca en la lista.

Resultado esperado: El servidor aparece en la lista sin errores.

Si falla: Revisa la ruta en mcp.json y que el JSON sea válido.

🔍 7. Validar modelo

Qué validar: Que el modelo use la herramienta cuando corresponde.

Cómo validar: Escribe una pregunta que requiera datos actuales (ej: “¿Qué hora es ahora?”).

Resultado esperado: El modelo usa la herramienta web_search y devuelve una respuesta con citas.

Si falla: Cambia a un modelo compatible (ej: qwen2.5-7b-instruct) y revisa el System Prompt.

Errores comunes y soluciones

❌ Python no encuentra el módulo

Causa: Las dependencias no están instaladas o no estás en el entorno correcto.

Solución:

• Reinstala las dependencias:

  pip install --upgrade "mcp[cli]>=1.2,<2" requests ddgs tavily-python

• Verifica que estás usando el mismo entorno donde instalaste los paquetes:

  which python   # Linux/macOS
    where python   # Windows

• Si usas un entorno virtual, actívalo antes de ejecutar el script.

❌ LM Studio no carga el servidor MCP

Causa: La ruta del archivo es incorrecta o el formato de mcp.json es inválido.

Solución:

• Verifica que la ruta en mcp.json sea absoluta y correcta.
• Usa doble barra invertida (\\) en Windows.
• Comprueba que el archivo mcp.json esté en ~/.lmstudio/.
• Valida el JSON en JSONLint.
• Reinicia LM Studio por completo.

❌ MCP no aparece en LM Studio

Causa: Versión de LM Studio desactualizada o archivo mcp.json mal ubicado.

Solución:

• Actualiza LM Studio a la versión 0.4.16 o superior.
• Verifica que el archivo esté en ~/.lmstudio/mcp.json.
• Reinicia tu computadora si el problema persiste.
• Prueba con un archivo mcp.json mínimo:

  {
      "mcpServers": {}
    }

  y luego añade tu servidor.

❌ Error de autenticación en la API

Causa: La clave API es inválida o el proveedor espera un formato distinto.

Solución:

• Verifica que la clave API sea correcta (cópiala y pégala de nuevo).
• Comprueba que el proveedor espere un encabezado Authorization, X-API-KEY o similar.
• Revisa la documentación del proveedor para confirmar el formato de la petición.
• Prueba la API directamente con curl (ver Paso 10.5).

❌ La búsqueda devuelve resultados vacíos

Causa: La consulta es demasiado genérica o el proveedor no tiene acceso a la información.

Solución:

• Usa una consulta más específica:

  # Mal: "dólar"
    # Bien: "tipo de cambio dólar México hoy 21 junio 2026"

• Prueba con otro proveedor (ej: si usas DDGS, cambia a Tavily).
• Aumenta el número de resultados:

  max_results=10  # En el código o en la petición

• Verifica que el proveedor tenga acceso a la información que buscas (ej: DDGS no es bueno para datos en tiempo real).

❌ El modelo ignora la herramienta

Causa: El modelo no está configurado para usar herramientas o el prompt no es claro.

Solución:

• Usa un modelo compatible con function calling:

  qwen2.5-7b-instruct  # Recomendado
    llama-3.1-8b-instruct

• Mejora el System Prompt para que sea más estricto:

  SI LA PREGUNTA REQUIERE DATOS ACTUALIZADOS, DEBES usar web_search. No hay excepciones.

• Haz preguntas que requieran datos actuales:

  "¿Qué hora es ahora en Ciudad de México?"
    "¿Cuál es el precio del Bitcoin hoy?"

• Activa Show debug info blocks in chat en Developer para ver logs.

❌ El servidor MCP crashea al iniciar

Causa: Error en el código o dependencias faltantes.

Solución:

• Ejecuta el servidor manualmente para ver el error:

  python mcp_web_search.py

• Verifica que todas las dependencias estén instaladas:

  pip list | grep -E "mcp|requests|ddgs|tavily"

• Revisa que no haya errores de sintaxis en el código (usa python -m py_compile mcp_web_search.py).

Seguridad: Buenas prácticas

Las claves API son sensibles. Sigue estas buenas prácticas para protegerlas:

🔒 1. Nunca guardes claves en el código

• Usa siempre variables de entorno o archivos .env.
• Ejemplo de lo que NO debes hacer:

  # ❌ MAL
  API_KEY = "tu_clave_api_secreta"

• Ejemplo de lo que SÍ debes hacer:

  # ✅ BIEN
  API_KEY = os.getenv("TAVILY_API_KEY")

🔒 2. No compartas claves en repositorios públicos

• Nunca subas claves API a GitHub, GitLab u otros repositorios.
• Usa .gitignore para excluir archivos con claves.

🔒 3. Usa .gitignore

Crea un archivo .gitignore en la raíz de tu proyecto:

# Claves API y configuraciones sensibles
*.env
*.json
!.gitignore
__pycache__/
*.pyc
venv/
.mcp/

🔒 4. Rota claves periódicamente

• Cambia tus claves API cada cierto tiempo (ej: cada 3 meses).
• Si una clave se expone accidentalmente, revócala inmediatamente en el panel del proveedor.

🔒 5. Usa permisos restrictivos

• En Linux/macOS, limita los permisos de los archivos con claves:

  chmod 600 ~/.lmstudio/mcp.json

• En Windows, usa el Administrador de credenciales para guardar claves de forma segura.

🔒 6. Evita commitear claves con git-secrets

Instala git-secrets para evitar commitear claves accidentalmente:

# Instalar git-secrets
git secrets --install

# Añadir patrones de claves API
git secrets --add 'TAVILY_API_KEY'
git secrets --add 'SERPER_API_KEY'
git secrets --add 'BING_API_KEY'
git secrets --add 'API_KEY'

# Escanear el repositorio
git secrets --scan

Alternativas si MCP no funciona

Si la integración con MCP en LM Studio no funciona, aquí tienes alternativas probadas:

🔹 Opción 1: Open WebUI (Recomendado)

Open WebUI es un frontend para LM Studio que soporta herramientas externas de manera nativa.

Ventajas:

• Más estable que MCP en algunas versiones de LM Studio.
• Interfaz gráfica amigable.
• Soporte para múltiples herramientas.
• Fácil de configurar.

Cómo instalar:

1. Instala Docker (si no lo tienes):
   • Windows/macOS: Descarga Docker Desktop desde docker.com.
   • Linux: Instala Docker con:

     sudo apt-get update
         sudo apt-get install docker-ce docker-ce-cli containerd.io

2. Ejecuta Open WebUI con Docker:

   docker run -d -p 3000:8080 \
       -e OPENAI_API_BASE_URL=http://host.docker.internal:1234/v1 \
       -e OPENAI_API_KEY=lm-studio \
       -e TAVILY_API_KEY=tu_clave_api \
       --add-host=host.docker.internal:host-gateway \
       -v open-webui:/app/backend/data \
       ghcr.io/open-webui/open-webui:main

3. Accede a http://localhost:3000.
4. Configura la herramienta web_search:
   1. Ve a Workspace > Functions > Create Function.
   2. Pega el siguiente código:

   import os
   import requests
   
   def web_search(query: str) -> str:
       """Busca información actualizada en internet."""
       api_key = os.getenv("TAVILY_API_KEY")
       if not api_key:
           return "Error: TAVILY_API_KEY no configurada."
   
       try:
           response = requests.post(
               "https://api.tavily.com/search",
               json={
                   "api_key": api_key,
                   "query": query,
                   "max_results": 5,
                   "search_depth": "basic"
               }
           )
           response.raise_for_status()
           data = response.json()
           results = data.get("results", [])
   
           if not results:
               return "No se encontraron resultados."
   
           formatted = []
           for i, r in enumerate(results, 1):
               formatted.append(
                   f"[Fuente {i}]\nTítulo: {r.get('title', 'Sin título')}\n"
                   f"Contenido: {r.get('content', '')}\n"
                   f"URL: {r.get('url', '')}"
               )
           return "\n\n".join(formatted)
   
       except Exception as e:
           return f"Error al buscar: {e}"

5. Guarda la función.
6. En Valves, configura TAVILY_API_KEY con tu clave.

📌 Ejemplo de uso en Open WebUI:

Escribe en el chat:

¿Cuál es el precio del Bitcoin hoy?

El modelo usará automáticamente la herramienta web_search y te responderá con los datos actualizados.

🔹 Opción 2: LiteLLM como proxy

LiteLLM actúa como un proxy entre tu aplicación y LM Studio, permitiendo el uso de herramientas.

Ventajas:

• Permite usar herramientas con cualquier modelo compatible con OpenAI.
• Soporte para múltiples proveedores de API.

Cómo instalar:

1. Instala LiteLLM:

   pip install litellm tavily-python

2. Ejecuta LiteLLM como proxy:

   litellm --model openai/gemma-4-e4b-it \
       --api_base http://127.0.0.1:1234/v1 \
       --port 8000

3. Configura LM Studio para que apunte a http://127.0.0.1:8000 en lugar de 1234.
4. Ahora, cuando uses un modelo en LM Studio, LiteLLM interceptará las llamadas a herramientas y las ejecutará.

🔹 Opción 3: Usar un script Python directamente

Si no quieres usar MCP, puedes ejecutar el script mcp_web_search.py directamente desde la terminal:

python mcp_web_search.py "¿Cuál es el tipo de cambio del dólar hoy?"

Ventajas:

• No requiere configuración en LM Studio.
• Útil para pruebas rápidas.

Desventajas:

• No es automático (debes ejecutar el script manualmente).

Checklist final

Antes de considerar la integración como completa, verifica cada punto:

• [ ] Python 3.10+ está instalado y funcionando (python --version).
• [ ] Las dependencias (mcp, requests, ddgs, tavily-python) están instaladas (pip list).
• [ ] La clave API del proveedor está configurada como variable de entorno.
• [ ] El servidor MCP (mcp_web_search.py) arranca sin errores (python mcp_web_search.py).
• [ ] El archivo mcp.json está en ~/.lmstudio/ con la ruta correcta.
• [ ] LM Studio 0.4.16+ lee el archivo mcp.json y muestra el servidor en la lista.
• [ ] El modelo cargado soporta function calling (ej: qwen2.5-7b-instruct).
• [ ] El System Prompt está configurado para usar la herramienta.
• [ ] Una prueba con una pregunta que requiera datos actuales funciona correctamente.

Ejemplo de flujo exitoso

📌 Escenario: Quieres saber el tipo de cambio del dólar hoy en México.

🔹 Paso 1: Usuario escribe en LM Studio:

¿Cuál es el tipo de cambio del dólar hoy en México?

🔹 Paso 2: LM Studio procesa la pregunta:

• El modelo detecta que la pregunta requiere datos actuales.
• Llama a la herramienta web_search("tipo de cambio dólar México hoy").

🔹 Paso 3: Servidor MCP ejecuta la búsqueda:

• El servidor MCP recibe la petición.
• Consulta la API de Tavily con la query.
• Devuelve los resultados al modelo.

🔹 Paso 4: Modelo responde:

> Calling web_search("tipo de cambio dólar México hoy")...
> Got results from 4 sources...

Según las fuentes, el tipo de cambio del dólar hoy en México es:
- Compra: $17.50 MXN [Fuente 1]
- Venta: $18.00 MXN [Fuente 2]
Actualizado: 21/06/2026 14:30hs [Fuente 1]

Fuentes:
- https://www.bancodemexico.gob.mx [Fuente 1]
- https://www.xe.com [Fuente 2]

Próximos pasos

Si ya tienes todo funcionando, aquí hay ideas para mejorar tu configuración:

🔹 1. Añadir más herramientas al servidor MCP

Puedes extender el servidor MCP con más funciones. Ejemplos:

📌 Herramienta para consultar el clima

Usa la API de OpenWeatherMap:

@mcp.tool()
def clima_actual(ciudad: str) -> str:
    """Devuelve el clima actual en una ciudad."""
    api_key = os.getenv("OPENWEATHER_API_KEY")
    if not api_key:
        return "Error: OPENWEATHER_API_KEY no configurada."

    try:
        url = f"https://api.openweathermap.org/data/2.5/weather?q={ciudad}&appid={api_key}&units=metric&lang=es"
        resp = requests.get(url)
        resp.raise_for_status()
        data = resp.json()

        temp = data["main"]["temp"]
        humedad = data["main"]["humidity"]
        descripcion = data["weather"][0]["description"]

        return f"Clima en {ciudad}: {descripcion}, Temperatura: {temp}°C, Humedad: {humedad}%"

    except Exception as e:
        return f"Error al consultar el clima: {e}"

Cómo obtener la API de OpenWeatherMap:

1. Regístrate en OpenWeatherMap.
2. Ve a API Keys y genera una clave.
3. Configúrala como variable de entorno: OPENWEATHER_API_KEY=tu_clave.

📌 Herramienta para calcular operaciones matemáticas

@mcp.tool()
def calcular(expresion: str) -> str:
    """Calcula el resultado de una expresión matemática."""
    try:
        # Usar eval es peligroso, pero para este ejemplo es simple
        resultado = eval(expresion)
        return f"Resultado: {resultado}"
    except Exception as e:
        return f"Error al calcular: {e}"

🔹 2. Implementar caché de resultados

Para evitar gastar créditos de API en consultas repetidas, implementa un sistema de caché:

from datetime import datetime, timedelta
import json
import os

# Archivo para guardar la caché
CACHE_FILE = "search_cache.json"

def load_cache():
    if os.path.exists(CACHE_FILE):
        with open(CACHE_FILE, "r") as f:
            return json.load(f)
    return {}

def save_cache(cache):
    with open(CACHE_FILE, "w") as f:
        json.dump(cache, f)

@mcp.tool()
def web_search(query: str) -> str:
    cache = load_cache()

    # Verificar si la consulta está en caché y no ha expirado (1 hora)
    if query in cache:
        cached = cache[query]
        if datetime.now() - datetime.fromisoformat(cached["timestamp"]) < timedelta(hours=1):
            return cached["result"]

    # Si no está en caché o expiró, hacer la búsqueda
    result = _do_web_search(query)  # Función que implementa la búsqueda real

    # Guardar en caché
    cache[query] = {"result": result, "timestamp": datetime.now().isoformat()}
    save_cache(cache)

    return result

🔹 3. Desplegar el servidor MCP en la nube

Si quieres acceder a tu modelo desde cualquier lugar, despliega el servidor MCP en un servicio como:

• Render (gratis para proyectos pequeños).
• Railway (gratis con límite).
• Fly.io (gratis para proyectos pequeños).

Ejemplo para Render:

1. Sube tu código a un repositorio de GitHub.
2. Crea una cuenta en Render.
3. Conecta tu repositorio y configura un Web Service.
4. Establece el comando de inicio: python mcp_web_search.py.
5. Despliega el servicio.

Recursos adicionales

Documentación oficial y recursos útiles:

📚 Documentación oficial

• LM Studio Docs – Documentación oficial de LM Studio.
• MCP Official Docs – Documentación del Model Context Protocol.
• Tavily API Docs – Documentación de la API de Tavily.
• Serper API Docs – Documentación de la API de Serper.
• DDGS GitHub – Librería DDGS para DuckDuckGo.

🎥 Tutoriales en video

• Cómo configurar MCP en LM Studio (inglés).
• Integración de Tavily con Python (español).

💬 Comunidades y soporte

• LM Studio Discord – Comunidad oficial de LM Studio.
• MCP GitHub – Repositorio oficial del SDK de MCP en Python.