MCP Web Research Agent for macOS

Ein Python Model Context Protocol (MCP)-Agent/Server, der einem lokalen KI-Assistenten Werkzeuge bereitstellt:

• search_web — öffentliche Websuche über DuckDuckGo-HTML-Ergebnisse

• fetch_url — eine öffentliche Webseite abrufen und lesbaren Text extrahieren

• save_note — Recherche-Notizen als Markdown-/Textdateien in einem Ordner deiner Wahl speichern

Das Projekt enthält außerdem agent.py, eine kleine lokale Brücke, die Ollama mit dem MCP-Server verbindet. Ollama führt das LLM aus; dieses Projekt stellt die MCP-Werkzeuge und die Agent-Schleife für Tool-Aufrufe bereit.

Hinweis: Ollama selbst ist ein Modellserver und kein nativer MCP-Client. Um Ollama mit MCP-Werkzeugen zu verwenden, führe hier agent.py oder einen anderen MCP-Bridge/Client aus.

Voraussetzungen

• MacBook Pro mit macOS

• Python 3.11 oder neuer (das mcp-Paket erfordert Python 3.10+; das Setup bevorzugt 3.13/3.12/3.11)

• Ollama installiert und ausgeführt

• Ein lokales Modell mit Tool-Calling-Unterstützung. Empfohlene Ausgangspunkte:

  • qwen2.5:7b für Macs mit 16 GB RAM

  • qwen2.5:14b falls du genug RAM/Leistung hast

  • qwen3:14b falls deine Ollama-Version es gut unterstützt

Related MCP server: Local Research MCP Server

1. Installation

Terminal öffnen und ausführen:

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

Falls du kein Python 3.11+ hast:

brew install python

2. Ollama installieren und starten

Installiere Ollama über https://ollama.com oder mit Homebrew:

brew install --cask ollama

Öffne die Ollama-App einmal und lade ein Modell:

ollama pull qwen2.5:7b
ollama serve

Überprüfe in einem anderen Terminal-Tab, ob Ollama läuft:

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

3. Den lokalen Ollama-MCP-Agent ausführen

Aus dem Projektordner:

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

Stelle dann zum Beispiel eine Frage:

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

One-shot-Modus:

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

Ein anderes Modell verwenden:

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

Lege fest, wo Notizen gespeichert werden:

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

4. Verwendung mit Claude Desktop

Wenn du möchtest, dass Claude Desktop sich direkt mit dem MCP-Server verbindet, bearbeite:

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

Füge hinzu:

{
  "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"
      }
    }
  }
}

Ersetze YOUR_USERNAME durch deinen Mac-Benutzernamen. Erstelle die Datei, falls sie nicht existiert. Starte Claude Desktop nach der Bearbeitung neu.

5. Verwendung mit Cursor

Erstelle oder bearbeite .cursor/mcp.json in einem Workspace:

{
  "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"
      }
    }
  }
}

Starte Cursor danach neu oder lade seine MCP-Einstellungen neu.

Tool-Referenz

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

Gibt die Suchergebnisse als JSON zurück:

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

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

Ruft eine http/https-URL ab und gibt den extrahierten Text zurück. Es vermeidet JavaScript-Rendering und funktioniert daher am besten mit normalen HTML-Seiten.

save_note(filename: str, content: str)

Speichert eine Notiz in MCP_NOTES_DIR. Das Standardverzeichnis ist:

~/MCPWebResearch/notes

Das Tool bereinigt Dateinamen und blockiert Pfad-Traversal.

Konfiguration

Umgebungsvariablen:

• OLLAMA_MODEL — Standardmodell, das von agent.py verwendet wird; Standard ist qwen2.5:7b

• OLLAMA_URL — OpenAI-kompatibler Ollama-Chat-Endpunkt; Standard ist http://localhost:11434/v1/chat/completions

• MCP_NOTES_DIR — Verzeichnis für gespeicherte Notizen

Beispiel:

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

Fehlerbehebung

Connection refused bei localhost:11434

Ollama wird nicht ausgeführt. Starte es mit:

ollama serve

Der Agent ruft keine Werkzeuge auf

Verwende ein Modell mit starker Tool-Calling-Unterstützung. qwen2.5:7b, qwen2.5:14b und ähnliche Qwen-Modelle sind gute Ausgangspunkte.

Eine Seite liefert nur wenig Text

Manche Websites blockieren Nicht-Browser-Clients oder benötigen JavaScript. Probiere andere Quellen aus oder verwende search_web und fetch_url zusammen.

Claude Desktop zeigt den Server nicht

Überprüfe Folgendes:

• Der Python-Pfad zeigt auf .venv/bin/python innerhalb dieses Projekts

• Der Pfad zu server.py ist absolut

• Die JSON-Datei enthält gültige Syntax

• Du hast Claude Desktop vollständig neu gestartet

Dateien

• server.py — MCP-Server mit Web-Research-Werkzeugen

• agent.py — lokaler Ollama-basierter MCP-Client/Agent-Loop

• requirements.txt — Python-Abhängigkeiten

Sicherheitshinweise

• Dieser Server kann öffentliche URLs abrufen und die öffentliche Websuche durchsuchen.

• Er kann Dateien nur in MCP_NOTES_DIR schreiben.

• Er führt keine Shell-Befehle aus.

• Prüfe gespeicherte Notizen und Quellenangaben, bevor du dich auf sie verlässt.

Zweiter MCP-Agent: Local Planner

Das Repository enthält jetzt einen zweiten MCP-Server/Agent: local-planner. Er speichert Projekte, Aufgaben und Markdown-Notizen auf der Festplatte.

Funktionen

Werkzeuge:

• 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)

Standard-Datenverzeichnis:

~/MCPPlanner

Überschreibe es mit:

export MCP_PLANNER_DIR=~/Documents/my-planner

Den Ollama-Planner ausführen

bash run-planner.sh

One-shot-Modus:

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

Ein anderes Modell verwenden:

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

Planner-Daten an einem anderen Ort speichern:

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

Gute Planner-Prompts

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.

Claude-Desktop-Konfiguration für den Planner

Verwende:

claude_desktop_config.planner.example.json

Füge sie in folgender Datei ein:

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

Du kannst beide Server unter mcpServers zusammenführen, sodass Claude Web-Research- und Planungswerkzeuge sieht.

Cursor-Konfiguration für den Planner

Verwende:

cursor-mcp.planner.example.json

Dateien

• planner_server.py — MCP-Server für Projekte/Aufgaben/Notizen

• planner_agent.py — Ollama-Bridge/Agent für den Planner

• run-planner.sh — Launcher

Dritter MCP-Agent: Health & Habit Tracker

Das Repository enthält einen dritten MCP-Server/Agent zum Erfassen von Gewohnheiten, Workouts, Mahlzeiten und Körpermaßen. Alle Daten werden lokal unter MCP_HEALTH_DIR gespeichert (Standard ~/MCPHealth).

Dieses Werkzeug dient nur der persönlichen Aufzeichnung und stellt keine medizinische Beratung dar.

Werkzeuge

• 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)

Mit Ollama ausführen

bash run-health.sh

One-shot-Modus:

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

Ein anderes Modell oder Datenverzeichnis verwenden:

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

Gute 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.

Claude-Desktop- / Cursor-Konfigurationen

• claude_desktop_config.health.example.json

• cursor-mcp.health.example.json

Du kannst alle drei MCP-Server gemeinsam ausführen (Web-Research, Planner, Health), indem du jeden unter mcpServers listest.

Dateien

• health_server.py — MCP-Server

• health_agent.py — Ollama-Bridge/Agent

• run-health.sh — Launcher