MCP Web Research Agent для macOS

Python Model Context Protocol (MCP) агент/сервер, который предоставляет локальному ИИ-ассистенту инструменты для:

• search_web — публичный веб-поиск через HTML-результаты DuckDuckGo

• fetch_url — получение публичной веб-страницы и извлечение читаемого текста

• save_note — сохранение исследовательских заметок в виде Markdown/текстовых файлов в выбранную вами папку

Проект также включает agent.py — небольшой локальный мост, который соединяет Ollama с MCP-сервером. Ollama запускает LLM; этот проект предоставляет MCP-инструменты и цикл агента с вызовом инструментов.

Примечание: Ollama сама по себе является сервером моделей, а не нативным MCP-клиентом. Чтобы использовать Ollama с MCP-инструментами, запустите agent.py из этого проекта или другой MCP-мост/клиент.

Что вам нужно

• MacBook Pro с macOS

• Python 3.11 или новее (пакет mcp требует Python 3.10+; установка предпочитает 3.13/3.12/3.11)

• Ollama установлена и запущена

• Локальная модель с поддержкой вызова инструментов. Рекомендуемые отправные точки:

  • qwen2.5:7b для Mac с 16 ГБ ОЗУ

  • qwen2.5:14b если у вас достаточно ОЗУ/производительности

  • qwen3:14b если ваша версия Ollama хорошо её поддерживает

Related MCP server: Local Research MCP Server

1. Установка

Откройте Терминал и выполните:

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

Если у вас нет Python 3.11+:

brew install python

2. Установка и запуск Ollama

Установите Ollama с https://ollama.com или через Homebrew:

brew install --cask ollama

Откройте приложение Ollama один раз, затем загрузите модель:

ollama pull qwen2.5:7b
ollama serve

В другой вкладке Терминала проверьте, что Ollama запущена:

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

3. Запуск локального MCP-агента Ollama

Из папки проекта:

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

Затем задайте вопрос, например:

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

Одноразовый режим:

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

Использование другой модели:

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

Выбор места сохранения заметок:

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

4. Использование с Claude Desktop

Если вы хотите, чтобы Claude Desktop подключался напрямую к MCP-серверу, отредактируйте:

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

Добавьте:

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

Замените YOUR_USERNAME на ваше имя пользователя Mac. Создайте файл, если он не существует. Перезапустите Claude Desktop после редактирования.

5. Использование с Cursor

Создайте или отредактируйте .cursor/mcp.json в рабочей области:

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

Затем перезапустите Cursor или перезагрузите его MCP-настройки.

Справочник по инструментам

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

Возвращает результаты поиска в формате JSON:

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

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

Получает URL http/https и возвращает извлечённый текст. Он избегает рендеринга JavaScript, поэтому лучше всего работает с обычными HTML-страницами.

save_note(filename: str, content: str)

Сохраняет заметку в MCP_NOTES_DIR. Каталог по умолчанию:

~/MCPWebResearch/notes

Инструмент очищает имена файлов и блокирует обход пути.

Конфигурация

Переменные окружения:

• OLLAMA_MODEL — модель по умолчанию, используемая agent.py; по умолчанию qwen2.5:7b

• OLLAMA_URL — OpenAI-совместимая конечная точка чата Ollama; по умолчанию http://localhost:11434/v1/chat/completions

• MCP_NOTES_DIR — каталог для сохранённых заметок

Пример:

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

Устранение неполадок

Connection refused к localhost:11434

Ollama не запущена. Запустите её с помощью:

ollama serve

Агент не вызывает инструменты

Используйте модель с сильной поддержкой вызова инструментов. qwen2.5:7b, qwen2.5:14b и подобные модели Qwen — хорошие отправные точки.

Страница возвращает мало текста

Некоторые веб-сайты блокируют не-браузерные клиенты или требуют JavaScript. Попробуйте другой источник или используйте search_web и fetch_url вместе.

Claude Desktop не показывает сервер

Проверьте, что:

• Путь к Python указывает на .venv/bin/python внутри этого проекта

• Путь к server.py является абсолютным

• JSON-файл имеет корректный синтаксис

• Вы полностью перезапустили Claude Desktop

Файлы

• server.py — MCP-сервер с инструментами веб-исследований

• agent.py — локальный MCP-клиент/цикл агента на базе Ollama

• requirements.txt — зависимости Python

Примечания по безопасности

• Этот сервер может получать публичные URL и искать в публичном вебе.

• Он может записывать файлы только в MCP_NOTES_DIR.

• Он не выполняет команды оболочки.

• Проверяйте сохранённые заметки и цитаты, прежде чем полагаться на них.

Второй MCP-агент: Local Planner

Репозиторий теперь включает второй MCP-сервер/агент: local-planner. Он хранит проекты, задачи и Markdown-заметки на диске.

Что он делает

Инструменты:

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

Каталог данных по умолчанию:

~/MCPPlanner

Переопределите его с помощью:

export MCP_PLANNER_DIR=~/Documents/my-planner

Запуск планировщика Ollama

bash run-planner.sh

Одноразовый режим:

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

Использование другой модели:

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

Хранение данных планировщика в другом месте:

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

Хорошие подсказки для планировщика

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 для планировщика

Используйте:

claude_desktop_config.planner.example.json

Добавьте это в:

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

Вы можете объединить оба сервера в mcpServers, чтобы Claude видел инструменты веб-исследований и планирования.

Конфигурация Cursor для планировщика

Используйте:

cursor-mcp.planner.example.json

Файлы

• planner_server.py — MCP-сервер для проектов/задач/заметок

• planner_agent.py — мост/агент Ollama для планировщика

• run-planner.sh — лаунчер

Третий MCP-агент: Health & Habit Tracker

Репозиторий включает третий MCP-сервер/агент для отслеживания привычек, тренировок, приёмов пищи и измерений тела. Все данные хранятся локально в MCP_HEALTH_DIR (по умолчанию ~/MCPHealth).

Этот инструмент предназначен только для личного отслеживания и не предоставляет медицинских рекомендаций.

Инструменты

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

Запуск с Ollama

bash run-health.sh

Одноразовый режим:

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

Использование другой модели или каталога данных:

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

Хорошие подсказки

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

• claude_desktop_config.health.example.json

• cursor-mcp.health.example.json

Вы можете запускать все три MCP-сервера вместе (веб-исследования, планировщик, здоровье), перечислив каждый в mcpServers.

Файлы

• health_server.py — MCP-сервер

• health_agent.py — мост/агент Ollama

• run-health.sh — лаунчер