ollama-mcp-websearch

# 🔎 Ollama MCP WebSearch Agent A minimal **Model Context Protocol (MCP)** server built in Python that integrates **web search** into any MCP-compatible client.\ This project demonstrates how to extend MCP servers with real-world tools, using both **DuckDuckGo (ddgs)** and the **new Ollama Web Search API (Sept 2025)**. ------------------------------------------------------------------------ ## ✨ Features - MCP server exposing two search tools: - `search_duckduckgo` → DuckDuckGo search (local, no API key needed)\ - `search_ollama` → Ollama's new web search API (requires API key)\ - Demo client included to test both providers.\ - `.env` file support for clean configuration management.\ - Clean modular structure, easy to extend with other tools (summarization, RAG, etc.). ------------------------------------------------------------------------ ## 📂 Project Structure ollama-mcp-websearch/ ├── backend/ │ ├── server.py # MCP server implementation │ ├── __init__.py │ └── tools/ │ └── web_search.py # DuckDuckGo search tool ├── client_demo/ │ └── test_client.py # Local demo client for testing ├── .env.example # Example environment file ├── requirements.txt └── README.md ------------------------------------------------------------------------ ## ⚡ Getting Started ### 1. Clone the repository ``` bash git clone https://github.com/<your-username>/ollama-mcp-websearch.git cd ollama-mcp-websearch ``` ### 2. Setup virtual environment ``` bash python3 -m venv .venv source .venv/bin/activate ``` ### 3. Install dependencies ``` bash pip install -r requirements.txt ``` *(if you see a warning about `duckduckgo-search`, uninstall it and use `pip install ddgs` instead)* ------------------------------------------------------------------------ ## 🌱 Environment Setup This project uses a `.env` file for configuration.\ Copy the provided `.env.example` and update it: ``` bash cp .env.example .env ``` Edit `.env`: ``` ini # 🔑 Ollama API Key (required only for Ollama cloud web search) OLLAMA_API_KEY=your_api_key_here # Default provider (optional: duckduckgo or ollama) DEFAULT_PROVIDER=duckduckgo ``` ### Notes: - `duckduckgo` works locally, no API key needed.\ - `ollama` requires an **Ollama API key** (cloud-backed web search).\ - The `.env` file is ignored by Git for security. ------------------------------------------------------------------------ ## ▶️ Usage ### Run the MCP server ``` bash python -m backend.server ``` ### Run the demo client Open another terminal, activate your venv again, then run: ``` bash # DuckDuckGo (local, always works) python -m client_demo.test_client duckduckgo # Ollama (requires OLLAMA_API_KEY) python -m client_demo.test_client ollama ``` ------------------------------------------------------------------------ ## 📌 Example Output 🔎 DuckDuckGo Results for: latest ASX news on BHP 1. BHP stock surges after quarterly report https://example.com/article1 BHP has announced strong results with iron ore production... 🔎 Ollama Web Search Results for: latest ASX news on BHP 1. BHP shares rise after earnings https://example.com/ollama1 Latest market response to BHP results... ------------------------------------------------------------------------ ## 🛠 Tech Stack - **Python 3.11+** - **MCP server (Ollama Python SDK)** - **DuckDuckGo (ddgs) search** - **dotenv** for environment variable management ------------------------------------------------------------------------ ## 🚀 Future Extensions - Summarization of search results with Ollama (`mistral`, `llama3`, etc.).\ - Add multiple search providers (Bing, Google API).\ - Integrate into IDEs supporting MCP (Claude Desktop, Cursor). ------------------------------------------------------------------------ ## 📜 License MIT License. Free to use and extend. ------------------------------------------------------------------------ ## 🙌 Acknowledgements - [DuckDuckGo Search (ddgs)](https://pypi.org/project/ddgs/)\ - [Ollama MCP](https://github.com/ollama/ollama-python)\ - [Model Context Protocol](https://modelcontextprotocol.io/)