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

Getting an API Key

1. Go to ollama.com
2. Sign in to your account
3. Navigate to API settings
4. 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