Ollama MCP Server

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)

Installation

1. Clone the repository:

   git clone https://github.com/adrianpuiu/ollama-mcp-server.git
   cd ollama-mcp-server
   

2. Install dependencies:

   pip install -r requirements.txt
   

Configuration

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

# 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.

python ollama_mcp.py

2. Integration with Gemini CLI

To add this server to your Gemini CLI configuration:

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):

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

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

🧪 Testing

The project includes a comprehensive test suite.

# Run all tests
python test_ollama_mcp.py

Manual Test with 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 file for details.