Ollama MCP Server with Qwen3-Coder

A Model Context Protocol (MCP) server that provides web search, web fetch, and chat completion capabilities using Ollama's Qwen3-coder models. Designed to work seamlessly with Cursor IDE and other MCP-compatible clients.

Features

• Smart Model Selection: Automatically uses qwen3-coder:480b-cloud when API key is available, falls back to local models
• Web Search: Powered by Ollama's hosted search API
• Web Fetch: Retrieve and parse content from specific URLs
• Chat Completion: High-quality code-focused conversations with Qwen3-coder
• Search & Chat: Combined tool that searches the web and generates responses based on results
• Automatic Fallback: Falls back to local models (qwen3:4b, qwen3:7b, etc.) when cloud is unavailable

Installation

1. Clone or download this repository
2. Install dependencies using uv (recommended) or pip:

# Using uv (recommended)
uv sync

# Or using pip
pip install -e .

Configuration

Environment Variables

• OLLAMA_API_KEY (optional): Required for cloud models and web search/fetch functionality
• OLLAMA_HOST (optional): Ollama server URL (default: http://localhost:11434)

For Cursor IDE

1. Open Cursor IDE settings
2. Go to "Extensions" → "MCP" → "Manage MCP Servers"
3. Add the configuration from cursor-mcp-config.json:

{
  "mcpServers": {
    "ollama-qwen-mcp": {
      "type": "stdio", 
      "command": "uv",
      "args": ["run", "python", "-m", "ollamamcp.server"],
      "env": {
        "OLLAMA_API_KEY": "your_api_key_here_or_remove_for_local_only",
        "OLLAMA_HOST": "http://localhost:11434"
      }
    }
  }
}

For Other MCP Clients

The server can be run directly:

# With API key for cloud features
OLLAMA_API_KEY=your_key uv run python -m ollamamcp.server

# Local only (no web search/fetch)
uv run python -m ollamamcp.server

Available Tools

1. web_search

Perform web searches using Ollama's hosted API.

Parameters:

• query (str): Search query
• max_results (int): Maximum results (default: 3, max: 20)

Requires: OLLAMA_API_KEY

2. web_fetch

Fetch content from a specific URL.

Parameters:

• url (str): Absolute URL to fetch

Requires: OLLAMA_API_KEY

3. chat_completion

Generate responses using Qwen3-coder models.

Parameters:

• messages (list): Conversation messages
• model (str, optional): Override model selection
• temperature (float): Sampling temperature (default: 0.7)
• max_tokens (int, optional): Maximum tokens to generate

4. search_and_chat

Combined web search and chat completion.

Parameters:

• query (str): Search query and question
• search_results (int): Number of results (default: 3)
• model (str, optional): Override model selection
• temperature (float): Sampling temperature (default: 0.7)

Requires: OLLAMA_API_KEY

5. get_available_models

Get information about available models and configuration.

Returns: Current model, availability status, and model lists.

Model Fallback Strategy

1. Cloud First: qwen3-coder:480b-cloud (if API key available)
2. Local Fallbacks (in order):
   • qwen3:4b
   • qwen3:7b
   • qwen3:14b
   • qwen2.5-coder:7b
   • qwen2.5-coder:3b
   • qwen2.5-coder:1.5b

The server automatically pulls local models if they're not available but Ollama is running.

Usage Examples

In Cursor IDE

Once configured, you can use natural language to:

• "Search for the latest Python async/await best practices"
• "Fetch the documentation from https://docs.python.org/3/library/asyncio.html"
• "What are the new features in the latest Django release?"

Direct API Usage

import json
import subprocess

# Example: Web search and chat
result = subprocess.run([
    "uv", "run", "python", "-m", "ollamamcp.server"
], input=json.dumps({
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "search_and_chat",
        "arguments": {
            "query": "latest Python asyncio patterns",
            "search_results": 5
        }
    }
}), text=True, capture_output=True)

print(result.stdout)

Requirements

• Python 3.12+
• Ollama (for local models)
• Internet connection (for cloud models and web search)

Troubleshooting

No Models Available

• Ensure Ollama is running: ollama serve
• Pull a local model: ollama pull qwen3:4b

Web Search/Fetch Not Working

• Verify OLLAMA_API_KEY is set and valid
• Check internet connection

Cloud Model Not Available

• Verify API key has access to cloud models
• Server will automatically fall back to local models

License

This project follows the same license as the Ollama Python library.