Skip to main content
Glama
akopper

ollama-websearch-mcp

by akopper
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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

Related MCP server: mcp-web-tools

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

  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

Available Tools

2 tools
web_fetchA

Fetch the content of a web page.

Args: url: The absolute URL to fetch.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It mentions the return dictionary structure but does not disclose potential side effects, error handling, rate limits, or that it is a read-only operation, though 'fetch' implies this.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with clear sections for purpose, arguments, and returns. Every sentence contributes value without unnecessary verbosity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and an output schema, the description is mostly complete. However, it lacks usage guidelines and does not mention any limitations or behavioral assumptions (e.g., whether it follows redirects).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds 'absolute URL' to the parameter meaning, but this is minimal and does not elaborate on format or examples. However, with only one parameter, the provided clarification is adequate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Fetch the content') and the resource ('a web page'). It also distinguishes itself from the sibling tool web_search by indicating direct URL fetching rather than searching.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus web_search or other alternatives. There is no explicit 'use when' or 'instead of' context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedweb_fetch
    • First observedweb_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

Web search and web fetch are clearly distinct operations with no overlap. An agent can easily tell them apart based on their names and descriptions.

Naming Consistency5/5

Both tools follow the same web_<verb> pattern, making the naming predictable and consistent. The convention is uniform across the entire set.

Tool Count3/5

Only two tools are provided, which feels thin for a general-purpose websearch server. The count is borderline but acceptable for a narrow scope.

Completeness4/5

Search and fetch cover the core operations for a websearch tool. Minor gaps exist (e.g., no advanced filtering or content extraction options), but no critical dead ends are apparent.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers