Agente de investigación web MCP para macOS

Un agente/servidor de Protocolo de Contexto de Modelo (MCP) en Python que proporciona a un asistente de IA local herramientas para:

• search_web — búsqueda web pública a través de los resultados HTML de DuckDuckGo

• fetch_url — obtener una página web pública y extraer texto legible

• save_note — guardar notas de investigación como archivos Markdown/texto en una carpeta que elijas

El proyecto también incluye agent.py, un pequeño puente local que conecta Ollama con el servidor MCP. Ollama ejecuta el LLM; este proyecto proporciona las herramientas MCP y el bucle de agente de llamada a herramientas.

Nota: Ollama en sí mismo es un servidor de modelos, no un cliente MCP nativo. Para usar Ollama con herramientas MCP, ejecuta agent.py aquí u otro puente/cliente MCP.

Requisitos

• MacBook Pro con macOS

• Python 3.11 o superior (el paquete mcp requiere Python 3.10+; la configuración prefiere 3.13/3.12/3.11)

• Ollama instalado y en ejecución

• Un modelo local de llamada a herramientas. Punto de partida recomendado:

  • qwen2.5:7b para Macs con 16 GB de RAM

  • qwen2.5:14b si tienes suficiente RAM/rendimiento

  • qwen3:14b si tu versión de Ollama lo soporta bien

Related MCP server: Local Research MCP Server

1. Instalación

Abre Terminal y ejecuta:

cd ~/Projects
git clone <your-repo-url> mcp-web-research-agent  # or copy this folder here
cd ~/Projects/mcp-web-research-agent

python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Si no tienes Python 3.11+:

brew install python

2. Instala e inicia Ollama

Instala Ollama desde https://ollama.com o con Homebrew:

brew install --cask ollama

Abre la aplicación de Ollama una vez y luego descarga un modelo:

ollama pull qwen2.5:7b
ollama serve

En otra pestaña de Terminal, verifica que Ollama esté en ejecución:

curl http://localhost:11434/api/tags

3. Ejecuta el agente MCP local de Ollama

Desde la carpeta del proyecto:

cd ~/Projects/mcp-web-research-agent
source .venv/bin/activate
python agent.py

Luego pregunta algo como:

Research recent MCP news, open the two best sources, summarize them, and save the summary as mcp-news.md.

Modo de una sola consulta:

python agent.py "Research current MCP SDK best practices and save notes."

Usa un modelo diferente:

python agent.py --model qwen2.5:14b

Elige dónde se guardan las notas:

python agent.py --notes-dir ~/Documents/research-notes

4. Úsalo con Claude Desktop

Si quieres que Claude Desktop se conecte directamente al servidor MCP, edita:

~/Library/Application Support/Claude/claude_desktop_config.json

Añade:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/YOUR_USERNAME/Projects/mcp-web-research-agent/.venv/bin/python",
      "args": [
        "/Users/YOUR_USERNAME/Projects/mcp-web-research-agent/server.py"
      ],
      "env": {
        "MCP_NOTES_DIR": "/Users/YOUR_USERNAME/Documents/MCP-research-notes"
      }
    }
  }
}

Reemplaza YOUR_USERNAME con tu nombre de usuario de Mac. Crea el archivo si no existe. Reinicia Claude Desktop después de editar.

5. Úsalo con Cursor

Crea o edita .cursor/mcp.json en un espacio de trabajo:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/YOUR_USERNAME/Projects/mcp-web-research-agent/.venv/bin/python",
      "args": [
        "/Users/YOUR_USERNAME/Projects/mcp-web-research-agent/server.py"
      ],
      "env": {
        "MCP_NOTES_DIR": "/Users/YOUR_USERNAME/Documents/MCP-research-notes"
      }
    }
  }
}

Luego reinicia Cursor o recarga su configuración de MCP.

Referencia de herramientas

search_web(query: str, max_results: int = 5)

Devuelve resultados de búsqueda como JSON:

{
  "query": "Model Context Protocol",
  "results": [
    {
      "title": "Example",
      "url": "https://example.com",
      "snippet": "..."
    }
  ]
}

fetch_url(url: str, max_chars: int = 8000)

Obtiene una URL http/https y devuelve el texto extraído. Evita el renderizado de JavaScript, por lo que funciona mejor en páginas HTML normales.

save_note(filename: str, content: str)

Guarda una nota en MCP_NOTES_DIR. El directorio predeterminado es:

~/MCPWebResearch/notes

La herramienta sanea los nombres de archivo y bloquea el recorrido de rutas.

Configuración

Variables de entorno:

• OLLAMA_MODEL — modelo predeterminado usado por agent.py; el valor predeterminado es qwen2.5:7b

• OLLAMA_URL — endpoint de chat de Ollama compatible con OpenAI; el valor predeterminado es http://localhost:11434/v1/chat/completions

• MCP_NOTES_DIR — directorio para las notas guardadas

Ejemplo:

export OLLAMA_MODEL=qwen2.5:14b
export MCP_NOTES_DIR=~/Documents/research-notes
python agent.py

Solución de problemas

Connection refused a localhost:11434

Ollama no se está ejecutando. Inícialo con:

ollama serve

El agente no llama a las herramientas

Usa un modelo con buen soporte de llamada a herramientas. qwen2.5:7b, qwen2.5:14b y modelos Qwen similares son buenos puntos de partida.

Una página devuelve poco texto

Algunos sitios web bloquean clientes que no son navegadores o requieren JavaScript. Prueba con otra fuente o usa search_web y fetch_url juntos.

Claude Desktop no muestra el servidor

Vuelve a comprobar que:

• La ruta de Python apunte a .venv/bin/python dentro de este proyecto

• La ruta de server.py sea absoluta

• El archivo JSON tenga una sintaxis válida

• Hayas reiniciado Claude Desktop por completo

Archivos

• server.py — servidor MCP con herramientas de investigación web

• agent.py — bucle de agente/cliente MCP local impulsado por Ollama

• requirements.txt — dependencias de Python

Notas de seguridad

• Este servidor puede obtener URLs públicas y buscar en la web pública.

• Solo puede escribir archivos en MCP_NOTES_DIR.

• No ejecuta comandos de shell.

• Revisa las notas y citas guardadas antes de confiar en ellas.

Segundo agente MCP: Planificador local

El repositorio ahora incluye un segundo servidor/agente MCP: local-planner. Almacena proyectos, tareas y notas de Markdown en disco.

Qué hace

Herramientas:

• create_project(name, description)

• list_projects()

• create_task(project, title, notes, priority, due_date, status)

• list_tasks(project, status)

• update_task(project, task_id, ...)

• complete_task(project, task_id)

• delete_task(project, task_id)

• save_project_note(project, content, append)

• get_daily_focus(for_date)

Directorio de datos predeterminado:

~/MCPPlanner

Reemplázalo con:

export MCP_PLANNER_DIR=~/Documents/my-planner

Ejecuta el planificador de Ollama

bash run-planner.sh

Una sola consulta:

bash run-planner.sh "Create a project called Weekend Yard Work with tasks for mowing, trimming bushes, and buying mulch."

Usa un modelo diferente:

bash run-planner.sh --model qwen2.5:14b

Almacena los datos del planificador en otro lugar:

bash run-planner.sh --data-dir ~/Documents/planner-data

Buenos prompts para el planificador

Create a project called Home Network Upgrade and break it into at least six tasks with priorities.

Look at my daily focus and tell me what I should work on first.

Create a moving checklist project with tasks, due dates, and notes.

Mark the first task in the Weekend Yard Work project complete and tell me what remains.

Configuración de Claude Desktop para el planificador

Usa:

claude_desktop_config.planner.example.json

Añádelo a:

~/Library/Application Support/Claude/claude_desktop_config.json

Puedes fusionar ambos servidores en mcpServers para que Claude vea las herramientas de investigación web y de planificación.

Configuración de Cursor para el planificador

Usa:

cursor-mcp.planner.example.json

Archivos

• planner_server.py — servidor MCP para proyectos/tareas/notas

• planner_agent.py — puente/agente de Ollama para el planificador

• run-planner.sh — lanzador

Tercer agente MCP: Seguimiento de salud y hábitos

El repositorio incluye un tercer servidor/agente MCP para hacer seguimiento de hábitos, entrenamientos, comidas y medidas corporales. Todos los datos se almacenan localmente en MCP_HEALTH_DIR (por defecto ~/MCPHealth).

Esta herramienta es solo para seguimiento personal y no proporciona asesoramiento médico.

Herramientas

• create_habit(name, description, target_per_week, unit)

• list_habits(active_only)

• log_habit(log_date, value, notes, habit_id|habit_name)

• log_workout(activity, duration_minutes, log_date, intensity, calories, distance_km, notes)

• log_meal(description, meal_type, log_date, calories, protein_g, carbs_g, fat_g, notes)

• log_measurement(weight_kg, log_date, body_fat_pct, waist_cm, notes)

• list_logs(log_type, from_date, to_date, limit)

• delete_log(log_id)

• save_health_note(content, append)

• get_daily_summary(for_date)

• get_weekly_report(for_date)

Ejecútalo con Ollama

bash run-health.sh

Una sola consulta:

bash run-health.sh "Create habits for a 30-min walk, drinking water, and stretching, then log today's walk and a lunch salad."

Usa un modelo o directorio de datos diferente:

bash run-health.sh --model qwen2.5:14b --data-dir ~/Documents/health-data

Buenos prompts

Create habits for walking 5 days per week, drinking 80 oz of water, and stretching daily.

Log a 45-minute moderate run today that burned 420 calories and covered 6 km.

Log my breakfast: oatmeal with banana and peanut butter, about 520 calories and 22 grams of protein.

Give me today's health summary and list habits I still need to complete.

Give me my weekly report and tell me which habits I'm behind on.

Configuraciones de Claude Desktop / Cursor

• claude_desktop_config.health.example.json

• cursor-mcp.health.example.json

Puedes ejecutar los tres servidores MCP juntos (investigación web, planificador, salud) enumerando cada uno en mcpServers.

Archivos

• health_server.py — servidor MCP

• health_agent.py — puente/agente de Ollama

• run-health.sh — lanzador