MCP Web Search System

A complete MCP (Model Context Protocol) implementation featuring a web search server and chat client powered by local Ollama models.

Architecture

┌─────────────────┐
│   Streamlit     │  (Port 8501)
│    Frontend     │  User Interface
└────────┬────────┘
         │
         ↓ HTTP
┌─────────────────┐
│   FastAPI       │  (Port 8001)
│  MCP Client     │  Orchestration Layer
└────┬────────┬───┘
     │        │
     ↓        ↓
┌─────────┐ ┌──────────────┐
│ Ollama  │ │ MCP Server   │  (Port 8000)
│ (Local) │ │ (FastMCP 3.0)│  Web Search
└─────────┘ └──────────────┘
                 │
                 ↓
            ┌─────────┐
            │ SerpAPI │
            └─────────┘

Features

• MCP Server: Web search capability using SerpAPI
• MCP Client: FastAPI-based orchestration layer
• Local LLM: Integration with Ollama models (qwen2.5:7b-instruct, llama3.2:3b, etc.)
• Web Interface: Clean Streamlit UI for chatting
• Intelligent Search: Automatic detection of queries requiring web search
• Streamable HTTP Transport: Modern MCP transport protocol

Prerequisites

1. Python 3.8+

2. Ollama installed and running locally

   • Download from: https://ollama.ai
   • Pull models:

     ollama pull qwen2.5:7b-instruct
     ollama pull llama3.2:3b
     ollama pull qwen2.5-coder:3b

3. SerpAPI Key

   • Sign up at: https://serpapi.com
   • Get your API key from the dashboard

Installation

1. Clone or download this project

cd /path/to/project

2. Create virtual environment (recommended)

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

Create a .env file (or set environment variables):

cp .env.example .env

Edit .env and add your SerpAPI key:

SERPAPI_API_KEY=your_actual_serpapi_key_here
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=qwen2.5:7b-instruct
MCP_SERVER_URL=http://localhost:8000

Running the System

You need to run three components in separate terminal windows:

Terminal 1: MCP Server (Web Search)

# Make sure SERPAPI_API_KEY is set
export SERPAPI_API_KEY='your-api-key-here'

# Run the MCP server
python search_mcp_server.py

Expected output:

Starting Web Search MCP Server...
Transport: Streamable HTTP
Port: 8000
Available tool: web_search

Terminal 2: FastAPI Client (Orchestration)

python mcp_client_api.py

Expected output:

Starting FastAPI MCP Client...
Ollama URL: http://localhost:11434
MCP Server URL: http://localhost:8000
Default Model: qwen2.5:7b-instruct
INFO:     Uvicorn running on http://0.0.0.0:8001

Terminal 3: Streamlit Frontend (UI)

streamlit run streamlit_app.py

Expected output:

You can now view your Streamlit app in your browser.
Local URL: http://localhost:8501

Usage

1. Open your browser to http://localhost:8501

2. Configure settings in the sidebar:

   • Select your Ollama model
   • Enable/disable web search
   • Refresh model list if needed

3. Start chatting:

   • Type your question in the chat input
   • The system automatically detects if web search is needed
   • View search results in expandable sections

Example Queries

Queries that trigger web search:

• "What's the latest news on AI?"
• "Search for Python async programming tutorials"
• "What is the current weather in New York?"
• "Find information about FastMCP 3.0"

Queries that don't need search:

• "Explain how async/await works in Python"
• "Write a function to calculate fibonacci numbers"
• "What is object-oriented programming?"

API Endpoints

FastAPI Client (Port 8001)

• POST /chat - Send chat message
• GET /tools - List available MCP tools
• GET /models - List available Ollama models
• GET /health - Health check

MCP Server (Port 8000)

• POST /mcp/v1/call_tool - Call MCP tool
• POST /mcp/v1/list_tools - List available tools

📁 Project Structure

.
├── search_mcp_server.py    # MCP server with web search tool
├── mcp_client_api.py       # FastAPI client connecting Ollama + MCP
├── streamlit_app.py        # Streamlit frontend
├── requirements.txt        # Python dependencies
├── .env.example           # Environment variable template
└── README.md              # This file

How It Works

1. User submits a query via Streamlit UI
2. FastAPI client receives the request
3. Query analysis determines if web search is needed
4. If search needed:
   • MCP client calls web_search tool on MCP server
   • MCP server queries SerpAPI and returns formatted results
   • Search results are added to the conversation context
5. Ollama LLM generates a response with search context
6. Response is displayed to the user with search attribution

Testing the MCP Server Directly

You can test the MCP server independently:

import httpx
import json

async def test_search():
    client = httpx.AsyncClient()
    
    payload = {
        "method": "tools/call",
        "params": {
            "name": "web_search",
            "arguments": {
                "query": "FastMCP 3.0 documentation",
                "num_results": 3
            }
        }
    }
    
    response = await client.post(
        "http://localhost:8000/mcp/v1/call_tool",
        json=payload
    )
    
    print(json.dumps(response.json(), indent=2))
    await client.aclose()

# Run with: python -m asyncio test_script.py

Troubleshooting

MCP Server won't start

• Check if port 8000 is already in use
• Verify SERPAPI_API_KEY is set correctly
• Ensure FastMCP 3.0+ is installed: pip install --upgrade fastmcp

FastAPI client errors

• Ensure Ollama is running: ollama list
• Check if MCP server is running on port 8000
• Verify model exists: ollama pull qwen2.5:7b-instruct

Streamlit connection issues

• Ensure FastAPI is running on port 8001
• Check browser console for CORS errors
• Try refreshing the page

No search results

• Verify SERPAPI_API_KEY is valid
• Check SerpAPI quota/limits
• Look at MCP server logs for errors

Additional Resources

• FastMCP Documentation
• MCP Protocol Specification
• Ollama Documentation
• SerpAPI Documentation
• FastAPI Documentation
• Streamlit Documentation

📄 License

This project is provided as-is for educational and demonstration purposes.

🙏 Acknowledgments

• FastMCP team for the excellent MCP implementation
• Anthropic for the MCP protocol
• Ollama team for local LLM capabilities
• SerpAPI for web search functionality