Ollama Search MCP Server

MCP server exposing Ollama's hosted web search and web fetch APIs as tools for any MCP client.

Overview

The server provides two tools:

• web_search: search the web through Ollama's hosted search API
• web_fetch: fetch a web page and return its content

It works with any MCP client, including Claude Desktop, Cursor, OpenCode, and MCPorter. An Ollama account and API key are required for the cloud endpoints.

Requirements

• Python 3.10+
• MCP Python SDK v2
• Ollama account (for cloud API access)

Installation

PyPI

uvx ollama-search-mcp
# or install the console script
pip install ollama-search-mcp

uvx runs the server on demand, which is the recommended command for MCP client configuration.

From Git

uvx --from git+https://github.com/akopper/ollama-search-mcp ollama-search-mcp

Pin a release with @<tag>:

uvx --from 'git+https://github.com/akopper/ollama-search-mcp@v0.2.1' ollama-search-mcp

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-search-mcp

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

Docker Compose

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

From Source

git clone https://github.com/akopper/ollama-search-mcp.git
cd ollama-search-mcp
pip install -e .

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

Search queries and fetched URLs are sent to Ollama's cloud service. Do not send confidential data in search queries.

Usage

Running the Server

stdio mode (default, for Claude Desktop/Cursor)

# Using the installed command
ollama-search-mcp

# Explicit stdio (same as the default)
ollama-search-mcp --stdio

# Or on demand with uvx
uvx ollama-search-mcp

# Or directly with Python
python -m ollama_search_mcp.server

HTTP mode (for remote usage)

python -m ollama_search_mcp.server --http

The server starts on http://localhost:8000/mcp by default. Use --host and --port to change the bind address, for example inside a container:

python -m ollama_search_mcp.server --http --host 0.0.0.0 --port 8000

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-search": {
      "command": "uvx",
      "args": ["ollama-search-mcp"],
      "env": {
        "OLLAMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

A globally installed ollama-search-mcp console script also works as command.

Cursor Integration

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

{
  "mcpServers": {
    "ollama-search": {
      "command": "uvx",
      "args": ["ollama-search-mcp"],
      "env": {
        "OLLAMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

OpenCode Integration

Add the server to your ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "servers": {
      "ollama-search": {
        "type": "local",
        "command": ["uvx", "ollama-search-mcp"],
        "environment": {
          "OLLAMA_API_KEY": "{env:OLLAMA_API_KEY}"
        }
      }
    }
  }
}

Then run opencode mcp list to verify the connection.

MCPorter Integration

MCPorter can discover and use this server. Example config/mcporter.json:

{
  "mcpServers": {
    "ollama-search": {
      "description": "Ollama web search and web fetch MCP server",
      "command": "uvx",
      "args": ["ollama-search-mcp"],
      "env": {
        "OLLAMA_API_KEY": "$env:OLLAMA_API_KEY"
      }
    }
  }
}

Or run ad-hoc:

# List tools
npx mcporter list ollama-search

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

Available Tools

web_search

Search the web through Ollama's hosted search API.

Parameters:

• query (required): the search query
• max_results (optional): maximum number of results (default: 10)

Returns: a dictionary with a results list; each entry contains title, url, and content.

web_fetch

Fetch a single web page.

Parameters:

• url (required): the absolute URL to fetch

Returns: a dictionary containing the page title, content, and links.

Development

Setup

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Or with uv
uv sync --extra dev

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov --cov-report=term-missing

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

Linting and Formatting

ruff check src/ tests/
ruff format --check src/ tests/

Building Distributions

python -m build
python -m twine check dist/*

Running the Server for Development

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

# Or run directly
python -m ollama_search_mcp.server

Releasing

See RELEASING.md for versioning, tagging, and PyPI trusted publishing.

License

MIT. See LICENSE.