# 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

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

### From Source

```bash
pip install -e .
```

### With uvx

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

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

For HTTP mode with uvx:

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

### Docker

The Docker image defaults to HTTP mode.

```bash
# 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

```bash
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](https://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)

```bash
# Using the installed command
ollama-websearch-mcp

# Or directly with Python
python -m ollama_websearch_mcp.server
```

#### HTTP mode (for remote usage)

```bash
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`

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

Or with a custom Python environment:

```json
{
  "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):

```json
{
  "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:

```json
// 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:

```bash
# 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

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

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

### Running Tests

```bash
# 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

```bash
# Check code style
ruff check src/ tests/

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

### Running the Server for Development

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

# Or run directly
python -m ollama_websearch_mcp.server
```

## License

MIT