MCP Web Research Agent for macOS

A Python Model Context Protocol (MCP) agent/server that gives a local AI assistant tools for:

• search_web — public web search via DuckDuckGo HTML results

• fetch_url — fetch a public web page and extract readable text

• save_note — save research notes as Markdown/text files in a folder you choose

The project also includes agent.py, a small local bridge that connects Ollama to the MCP server. Ollama runs the LLM; this project provides the MCP tools and the tool-calling agent loop.

Note: Ollama itself is a model server, not a native MCP client. To use Ollama with MCP tools, run agent.py here or another MCP bridge/client.

What you need

• MacBook Pro with macOS

• Python 3.11 or newer (the mcp package requires Python 3.10+; setup prefers 3.13/3.12/3.11)

• Ollama installed and running

• A tool-calling local model. Recommended starting point:

  • qwen2.5:7b for 16 GB RAM Macs

  • qwen2.5:14b if you have enough RAM/performance

  • qwen3:14b if your Ollama version supports it well

Related MCP server: Local Research MCP Server

1. Install

Open Terminal and run:

mkdir -p ~/Agents
cd ~/Agents
git clone https://github.com/jstrick9/mcp_agent.git
cd mcp_agent

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

setup-mac.sh does the same thing and will find or install Python 3.11+ for you:

bash setup-mac.sh

If you do not have Python 3.11+:

brew install python

Confirm the install works (no Ollama needed)

These two checks start the real MCP servers and drive the real agent loop against a mock Ollama endpoint. They need no network and no downloaded model, so they are the fastest way to confirm a fresh clone is healthy:

./.venv/bin/python tests/e2e_mcp.py
bash tests/e2e_agents.sh

You should see ALL CHECKS PASSED and ALL BRIDGE AGENT CHECKS PASSED. Together they exercise all 43 MCP tools plus one full tool call through each bridge agent.

2. Install and start Ollama

Install Ollama from https://ollama.com or with Homebrew:

brew install --cask ollama

Open the Ollama app once, then pull a model:

ollama pull qwen2.5:7b
ollama serve

In another Terminal tab, verify Ollama is running:

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

3. Run the local Ollama MCP agent

From the project folder:

cd ~/Agents/mcp_agent
source .venv/bin/activate
python agent.py

Then ask something like:

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

One-shot mode:

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

Use a different model:

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

Choose where notes are saved:

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

4. Use with Claude Desktop

All five servers at once

To register every agent in this repo with one paste, start from the generated combined config:

• claude_desktop_config.all.example.json — all five servers for Claude Desktop

• cursor-mcp.all.example.json — all five servers for Cursor

Replace YOUR_USERNAME with your macOS username, then merge the mcpServers object into:

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

Both files declare all five servers — web-research, local-planner, health-tracker, knowledge-base, and flashcards — each pointing at the shared .venv/bin/python and its own data directory.

These two files are generated, not hand-written. They are assembled from the per-agent example configs by:

./.venv/bin/python tools/build_combined_configs.py          # regenerate
./.venv/bin/python tools/build_combined_configs.py --check   # verify they are current

--check also confirms each entry's environment variable matches what the server script actually reads, so a renamed MCP_* variable cannot silently ship a broken config. The check runs as part of tests/e2e_mcp.py.

One server at a time

If you want Claude Desktop to connect directly to the MCP server, edit:

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

Add:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/YOUR_USERNAME/Agents/mcp_agent/.venv/bin/python",
      "args": [
        "/Users/YOUR_USERNAME/Agents/mcp_agent/server.py"
      ],
      "env": {
        "MCP_NOTES_DIR": "/Users/YOUR_USERNAME/MCPWebResearch/notes"
      }
    }
  }
}

Replace YOUR_USERNAME with your Mac username. Create the file if it does not exist. Restart Claude Desktop after editing.

5. Use with Cursor

Create or edit .cursor/mcp.json in a workspace:

{
  "mcpServers": {
    "web-research": {
      "command": "/Users/YOUR_USERNAME/Agents/mcp_agent/.venv/bin/python",
      "args": [
        "/Users/YOUR_USERNAME/Agents/mcp_agent/server.py"
      ],
      "env": {
        "MCP_NOTES_DIR": "/Users/YOUR_USERNAME/MCPWebResearch/notes"
      }
    }
  }
}

Then restart Cursor or reload its MCP settings.

Tool reference

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

Returns search results as JSON:

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

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

Fetches an http/https URL and returns extracted text. It avoids JavaScript rendering, so it works best on normal HTML pages.

save_note(filename: str, content: str)

Saves a note to MCP_NOTES_DIR. The default directory is:

~/MCPWebResearch/notes

The tool sanitizes filenames and blocks path traversal.

Configuration

Environment variables:

• OLLAMA_MODEL — default model used by agent.py; default is qwen2.5:7b

• OLLAMA_URL — OpenAI-compatible Ollama chat endpoint; default is http://localhost:11434/v1/chat/completions

• MCP_NOTES_DIR — directory for saved notes

Example:

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

Troubleshooting

Connection refused to localhost:11434

Ollama is not running. Start it with:

ollama serve

The agent does not call tools

Use a model with strong tool-calling support. qwen2.5:7b, qwen2.5:14b, and similar Qwen models are good starting points.

A page returns little text

Some websites block non-browser clients or require JavaScript. Try a different source, or use search_web and fetch_url together.

Claude Desktop does not show the server

Double-check that:

• The Python path points to .venv/bin/python inside this project

• The server.py path is absolute

• The JSON file has valid syntax

• You fully restarted Claude Desktop

Files

• server.py — MCP server with web research tools

• agent.py — local Ollama-powered MCP client/agent loop

• requirements.txt — Python dependencies

Safety notes

• This server can fetch public URLs and search the public web.

• It can write files only into MCP_NOTES_DIR.

• It does not execute shell commands.

• Review saved notes and citations before relying on them.

Second MCP agent: Local Planner

The repo now includes a second MCP server/agent: local-planner. It stores projects, tasks, and Markdown notes on disk.

What it does

Tools:

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

Default data directory:

~/MCPPlanner

Override it with:

export MCP_PLANNER_DIR=~/Documents/my-planner

Run the Ollama planner

bash run-planner.sh

One-shot:

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

Use a different model:

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

Store planner data elsewhere:

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

Good 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 config for planner

Use:

claude_desktop_config.planner.example.json

Add it to:

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

You can merge both servers under mcpServers so Claude sees web research and planning tools.

Cursor config for planner

Use:

cursor-mcp.planner.example.json

Files

• planner_server.py — MCP server for projects/tasks/notes

• planner_agent.py — Ollama bridge/agent for the planner

• run-planner.sh — launcher

Third MCP agent: Health & Habit Tracker

The repo includes a third MCP server/agent for tracking habits, workouts, meals, and body measurements. All data is stored locally under MCP_HEALTH_DIR (default ~/MCPHealth).

This tool is for personal tracking only and does not provide medical advice.

Tools

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

Run with Ollama

bash run-health.sh

One-shot:

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

Use a different model or data directory:

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

Good 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 configs

• claude_desktop_config.health.example.json

• cursor-mcp.health.example.json

You can run all five MCP servers together (web research, planner, health, knowledge base, flashcards) by listing each under mcpServers.

Files

• health_server.py — MCP server

• health_agent.py — Ollama bridge/agent

• run-health.sh — launcher

Fourth MCP agent: Personal Knowledge Base

A searchable long-term memory that ties the other three agents together. Your research agent, planner, and health tracker all write notes, but nothing could search them. This agent indexes those folders plus anything you save manually, with real full-text search.

Search uses SQLite's FTS5 extension with BM25 relevance ranking (both ship with Python, so there are no new dependencies). If FTS5 is unavailable on a platform, the server automatically falls back to substring search and reports "search_mode": "substring".

Data is stored under MCP_KB_DIR (default ~/MCPKnowledge) in a single SQLite file, kb.db.

Tools

• save_snippet(content, title, tags, source_url, source_path, source_type)

• search_kb(query, tag, limit, content_chars)

• list_snippets(tag, source_type, limit, content_chars)

• get_snippet(snippet_id)

• delete_snippet(snippet_id)

• list_tags()

• rename_tag(old_tag, new_tag)

• ingest_notes(directories, tag, recursive)

• kb_stats()

Import notes from your other agents

This is the highest-value first step. It pulls .md and .txt files into the index:

Ingest my notes from ~/MCPWebResearch/notes, ~/MCPPlanner, and ~/MCPHealth with the tag imported.

Re-running is safe: unchanged files are skipped, changed files are updated in place, and nothing is duplicated. Skips .git, .venv, and node_modules.

Run with Ollama

bash run-kb.sh

One-shot:

bash run-kb.sh "Ingest my research notes, then summarize everything I have saved about MCP."

Different model or database location:

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

Good prompts

Save this: FastMCP exposes Python functions as MCP tools via a decorator. Tag it python and mcp.

Search my knowledge base for stdio transport and cite the source of each result.

What do I have tagged mcp? List titles and sources.

Rename the tag py to python everywhere.

Give me knowledge base stats: how many entries, which sources, and my top tags.

Search syntax

search_kb passes your query to SQLite FTS5, so operators work:

If a query contains malformed FTS5 syntax, the server retries it as literal quoted phrases rather than failing, so unusual punctuation never produces an error.

Claude Desktop / Cursor configs

• claude_desktop_config.kb.example.json

• cursor-mcp.kb.example.json

You can run all four MCP servers together by listing each under mcpServers.

Files

• kb_server.py — MCP server with SQLite FTS5 search

• kb_agent.py — Ollama bridge/agent

• run-kb.sh — launcher

Safety notes

• The database and all writes stay inside MCP_KB_DIR.

• ingest_notes reads only the folders you explicitly pass to it.

• It reads .md and .txt files only, and never executes shell commands.

• Notes may contain personal information. Back up kb.db like any other data file.

Fifth MCP agent: Learning & Flashcards

A spaced-repetition study system. Build decks from anything you're learning, then review cards on a schedule that adapts to how well you actually remember them.

Scheduling uses the SM-2 algorithm (SuperMemo 2), the same family of algorithms Anki is built on. Cards you find hard come back sooner; cards you know well stretch out to weeks and months.

Data is stored under MCP_FLASHCARDS_DIR (default ~/MCPFlashcards) as three JSON files: decks.json, cards.json, and reviews.json.

Tools

• create_deck(name, description, tags)

• list_decks()

• delete_deck(deck)

• add_card(deck, front, back, tags, notes)

• edit_card(card_id, front, back, tags, notes)

• delete_card(card_id)

• list_cards(deck, tag, limit, due_only)

• get_due_cards(deck, limit, include_back)

• record_review(card_id, quality, seconds_spent, session_id, notes)

• get_review_session(session_id, for_date)

• get_stats(deck)

How grading works

record_review takes a quality score from 0 to 5:

Intervals progress 1 day, then 6 days, then each interval is the previous one multiplied by the card's ease factor (which starts at 2.5 and is clamped between 1.3 and whatever repeated perfect reviews build it to).

Run with Ollama

bash run-flashcards.sh

One-shot:

bash run-flashcards.sh "Create a deck called MCP Basics with 8 cards covering the protocol fundamentals."

Different model or data directory:

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

Reviews are interactive, so the REPL is the better fit:

bash run-flashcards.sh

You> What's due today? Quiz me on it.

The agent will show you each question, wait for your answer, then ask you to rate your recall from 0 to 5. It does not grade itself.

Good prompts

Create a deck called Spanish Food with 10 cards for common restaurant vocabulary.

Make flashcards from this: MCP servers expose tools over stdio, use JSON-RPC 2.0, and are spawned by the client.

Quiz me on MCP Basics, ten cards.

What's my retention this week and which cards do I keep failing?

Show my study stats and how many cards are due tomorrow.

Pair it with the knowledge base

The knowledge base agent can pull in notes you've saved, which makes good raw material for cards:

Search my knowledge base for mcp and make a flashcard deck from what you find.

Claude Desktop / Cursor configs

• claude_desktop_config.flashcards.example.json

• cursor-mcp.flashcards.example.json

You can run all five MCP servers together — see claude_desktop_config.all.example.json in the Use with Claude Desktop section.

Files

• flashcards_server.py — MCP server with SM-2 scheduling

• flashcards_agent.py — Ollama bridge/agent

• run-flashcards.sh — launcher

Safety notes

• All data stays inside MCP_FLASHCARDS_DIR.

• The server never executes shell commands or makes network calls.

• Review history is retained when you delete a deck, so get_stats stays meaningful.