Ollama WebSearch MCP Server

MCP server for Ollama web search and web fetch APIs.

Overview

This MCP server exposes two tools for interacting with Ollama's web services:

web_search: Perform a web search using Ollama's hosted search API
web_fetch: Fetch the content of a web page

Requirements

Python 3.10+
Ollama account (for cloud API access)

Installation

Clone

git clone https://github.com/akopper/ollama-websearch-mcp.git
cd ollama-websearch-mcp

From Source

pip install -e .

With uvx

uvx runs the server in stdio mode by default (for Claude Desktop/Cursor):

uvx --from https://github.com/akopper/ollama-websearch-mcp ollama-websearch-mcp

For HTTP mode with uvx:

uvx --from https://github.com/akopper/ollama-websearch-mcp ollama-websearch-mcp -- --http

Docker

The Docker image defaults to HTTP mode.

# HTTP mode (default) - for remote usage
docker run -d -p 8000:8000 -e OLLAMA_API_KEY=your-api-key ghcr.io/akopper/ollama-websearch-mcp

# stdio mode - for Claude Desktop/Cursor
docker run -it --rm -e OLLAMA_API_KEY=your-api-key ghcr.io/akopper/ollama-websearch-mcp --stdio

Docker Compose

cp .env.example .env
# Edit .env with your API key
docker-compose up -d

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | OLLAMA_API_KEY | API key for Ollama cloud services | None | | OLLAMA_HOST | Host URL for Ollama | https://ollama.com |

Getting an API Key

Go to ollama.com
Sign in to your account
Navigate to API settings
Generate an API key

Usage

Running the Server

stdio mode (default, for Claude Desktop/Cursor)

# Using the installed command
ollama-websearch-mcp

# Or directly with Python
python -m ollama_websearch_mcp.server

HTTP mode (for remote usage)

python -m ollama_websearch_mcp.server --http

The server will start on http://localhost:8000/mcp by default.

Claude Desktop Integration

Add the following to your Claude Desktop configuration:

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

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ollama-websearch": {
      "command": "ollama-websearch-mcp",
      "env": {
        "OLLAMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Or with a custom Python environment:

{
  "mcpServers": {
    "ollama-websearch": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "ollama_websearch_mcp.server"],
      "env": {
        "OLLAMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor Integration

Add to Cursor settings (or .cursor/mcp.json in project):

{
  "mcpServers": {
    "ollama-websearch": {
      "command": "ollama-websearch-mcp",
      "env": {
        "OLLAMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

MCPorter Integration

MCPorter can discover and use this MCP server. Create a config file:

// config/mcporter.json
{
  "mcpServers": {
    "ollama-websearch": {
      "description": "Ollama web search and web fetch MCP server",
      "command": "ollama-websearch-mcp",
      "env": {
        "OLLAMA_API_KEY": "$env:OLLAMA_API_KEY"
      }
    }
  }
}

Or run ad-hoc:

# List tools
npx mcporter list ollama-websearch

# Call a tool
npx mcporter call ollama-websearch.web_search query:python max_results:10

Available Tools

web_search

Perform a web search using Ollama's hosted search API.

Parameters:

query (required): The search query string
max_results (optional): Maximum number of results to return (default: 10)

Returns: Dictionary containing search results with title, url, and snippet.

web_fetch

Fetch the content of a web page.

Parameters:

url (required): The absolute URL to fetch

Returns: Dictionary containing the fetched content with html, text, and metadata.

Development

Setup

# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install with dev dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run a single test
pytest tests/test_server.py::TestWebSearch::test_web_search_returns_dict

# Run with verbose output
pytest -v

# Run with coverage
pytest --cov=src --cov-report=html

Linting

# Check code style
ruff check src/ tests/

# Auto-fix issues
ruff check src/ tests/ --fix

Running the Server for Development

# stdio mode with mcp dev
mcp dev src/ollama_websearch_mcp/server.py

# Or run directly
python -m ollama_websearch_mcp.server

License

MIT

ollama-websearch-mcp