# Ollama MCP Server

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP Server](https://img.shields.io/badge/MCP-Server-green.svg)](https://modelcontextprotocol.io/)

A production-grade **Model Context Protocol (MCP)** server that bridges Ollama's capabilities with MCP-compatible clients (like Cline, Codex, Goose). This server specifically provides **web search** and **content fetching** capabilities through the Ollama API, enabling AI models to access real-time information and reduce hallucinations.

## ✨ Features

*   ✅ **Web Search**: Search the internet for current information using `ollama_web_search`.
*   ✅ **Content Fetching**: specific URL content retrieval using `ollama_web_fetch`.
*   ✅ **Flexible Configuration**: Supports both **Ollama Cloud** (default) and **Local Ollama** endpoints.
*   ✅ **Type-Safe**: Built with `pydantic` for robust input validation.
*   ✅ **Async I/O**: High-performance, non-blocking operations using `httpx`.
*   ✅ **Easy Integration**: Seamlessly works with any MCP-compliant client.

## 🚀 Quick Start

### Prerequisites

*   Python 3.8 or higher
*   An Ollama API key (get it from [ollama.com/account](https://ollama.com/account))

### Installation

1.  **Clone the repository:**
    ```bash
    git clone https://github.com/adrianpuiu/ollama-mcp-server.git
    cd ollama-mcp-server
    ```

2.  **Install dependencies:**
    ```bash
    pip install -r requirements.txt
    ```

### Configuration

You **must** set the `OLLAMA_API_KEY` environment variable for the server to authenticate.

```bash
# Linux/macOS
export OLLAMA_API_KEY="your_actual_api_key_here"

# Windows (Command Prompt)
set OLLAMA_API_KEY=your_actual_api_key_here

# Windows (PowerShell)
$env:OLLAMA_API_KEY="your_actual_api_key_here"
```

## 🛠️ Usage

### 1. As a Standalone Server

You can run the server directly. It uses stdio for communication, so it will wait for input.

```bash
python ollama_mcp.py
```

### 2. Integration with Gemini CLI

To add this server to your Gemini CLI configuration:

```bash
gemini mcp add ollama_mcp python /absolute/path/to/ollama_mcp.py \
  -e OLLAMA_API_KEY=your_key_here \
  -s user
```

### 3. Integration with Cline / Codex

Add the following to your MCP configuration file (e.g., `~/.cline/config.json` or `~/.codex/config.toml`):

**JSON (Cline):**
```json
{
  "mcpServers": {
    "ollama_mcp": {
      "command": "python",
      "args": ["/absolute/path/to/ollama_mcp.py"],
      "env": {
        "OLLAMA_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}
```

## ⚠️ Important Note on Web Search

The **Web Search** (`ollama_web_search`) and **Web Fetch** (`ollama_web_fetch`) tools typically require the **Ollama Cloud API**.

*   **Default Behavior:** The server defaults to `https://ollama.com/api`.
*   **Local Ollama:** If you are running Ollama locally (`http://localhost:11434`), note that the standard local installation **does not** usually include the web search endpoints (`/api/web_search`).
*   **Recommendation:** Use the cloud endpoint for search features, even if you use a local instance for model inference.

If you encounter a **404 Not Found** error when searching, ensure you are using the cloud endpoint:

```bash
export OLLAMA_API_BASE_URL="https://ollama.com/api"
```

## 🧪 Testing

The project includes a comprehensive test suite.

```bash
# Run all tests
python test_ollama_mcp.py
```

**Manual Test with Python:**
```python
import asyncio
import os
from ollama_mcp import ollama_web_search, WebSearchInput

# Ensure API Key is set
os.environ["OLLAMA_API_KEY"] = "your_key_here"

async def main():
    params = WebSearchInput(query="latest AI news", max_results=3)
    result = await ollama_web_search(params)
    print(result)

if __name__ == "__main__":
    asyncio.run(main())
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.