MCP Web Research Agent for macOS

macOS向けのPython Model Context Protocol（MCP）エージェント/サーバーです。ローカルのAIアシスタントに以下のツールを提供します：

• search_web — DuckDuckGo HTML検索結果による公開ウェブ検索

• fetch_url — 公開ウェブページを取得して読みやすいテキストを抽出

• save_note — 選択したフォルダーに調査ノートをMarkdown/テキストファイルとして保存

このプロジェクトには、Ollama をMCPサーバーに接続する小さなローカルブリッジ agent.py も含まれています。Ollama がLLMを実行し、このプロジェクトがMCPツールとツール呼び出しエージェントループを提供します。

注：Ollama 自体はモデルサーバーであり、ネイティブなMCPクライアントではありません。Ollama をMCPツールで使用するには、ここで agent.py を実行するか、別のMCPブリッジ/クライアントを使用してください。

必要なもの

• macOS搭載のMacBook Pro

• Python 3.11 以上（mcpパッケージはPython 3.10+が必要です。セットアップでは3.13/3.12/3.11を推奨）

• Ollama がインストールされ実行中であること

• ツール呼び出し対応のローカルモデル。推奨の出発点：

  • 16GB RAMのMacでは qwen2.5:7b

  • 十分なRAM/性能がある場合は qwen2.5:14b

  • Ollamaのバージョンが対応していれば qwen3:14b

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 のインストールと起動

https://ollama.com からOllamaをインストールするか、Homebrewで：

brew install --cask ollama

Ollamaアプリを一度起動し、モデルをプル：

ollama pull qwen2.5:7b
ollama serve

別のターミナルタブで、Ollamaが実行中か確認：

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

3. ローカルの Ollama MCP エージェントを実行

プロジェクトフォルダから：

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)

http/https URLを取得し、抽出したテキストを返します。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

トラブルシューティング

localhost:11434 への Connection refused

Ollamaが実行されていません。次で起動してください：

ollama serve

ツールが呼び出されない

ツール呼び出しに対応したモデルを使用してください。qwen2.5:7b、qwen2.5:14b などのモデルが適しています。

ページから返されるテキストが少ない

一部のサイトはJavaScriptを必要とするか、ブラウザ以外のクライアントをブロックします。別のURLを試すか、search_web と fetch_url を組み合わせて使用してください。

Claude Desktop にサーバーが表示されない

以下を確認してください：

• パスが .venv/bin/python を指している（このプロジェクト内）

• server.py のパスが絶対パスである

• Claude Desktop を完全に再起動した

ファイル

• server.py — Webリサーチツールを備えたMCPサーバー

• agent.py — ローカルOllama対応のMCPクライアント/エージェントループ

• requirements.txt — Python依存関係

セキュリティに関する注意

• このサーバーは公開URLを取得し、公開ウェブ検索を実行できます。

• ファイルは MCP_NOTES_DIR にのみ書き込みます。それ以外の場所には書き込みません。

• シェルコマンドは実行しません。

• 信頼する前に、保存されたメモと引用を確認してください。

第2のMCPエージェント：ローカルプランナー

このリポジトリには、local-planner という2つ目のMCPサーバーが含まれています。プロジェクト、タスク、Markdownノートをディスクに保存します。

機能

ツール：

• create_project(name, description)

• list_projects()

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

• list_tasks(project, status)

• update_task(project, task_id, title, notes, status, priority, due_date)

• 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にWeb検索とプランニングの両方のツールを認識させることができます。

Cursor のプランナー設定

次を使用：

cursor-mcp.planner.example.json

ファイル

• planner_server.py — プロジェクト/タスク/メモ用のMCPサーバー

• planner_agent.py — プランナー用のOllamaブリッジ/エージェント

• run-planner.sh — ランチャー

3つ目のMCPエージェント: 健康・習慣トラッカー

このリポジトリには、習慣、ワークアウト、食事、身体測定値を追跡する3つ目のMCPサーバー/エージェントが含まれています。すべてのデータは MCP_HEALTH_DIR（デフォルトは ~/MCPHealth）の下にローカル保存されます。

このツールは個人の記録用のみで、医学的アドバイスを提供するものではありません。

ツール

• create_habit(name, description, target_per_week, unit)

• list_habits(active_only)

• log_habit(log_date, value, habit_id|habit_name)

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

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

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

• list_logs(log_type, from_date, to_date, limit)

• delete_log(log_id)

• save_health_note(content, append)

• get_daily_summary(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

ファイル

• health_server.py — MCPサーバー

• health_agent.py — Ollamaブリッジ/エージェント

• run-health.sh — ランチャー