Overview

MCP Client for Ollama (ollmcp) is a modern, interactive terminal application (TUI) for connecting local Ollama LLMs to one or more Model Context Protocol (MCP) servers, enabling advanced tool use and workflow automation. With a rich, user-friendly interface, it lets you manage tools, models, and server connections in real time—no coding required. Whether you're building, testing, or just exploring LLM tool use, this client streamlines your workflow with features like fuzzy autocomplete, advanced model configuration, MCP servers hot-reloading for development, and Human-in-the-Loop safety controls.

Features

• 🤖 Agent Mode: Iterative tool execution when models request multiple tool calls, with a configurable loop limit to prevent infinite loops
• 🌐 Multi-Server Support: Connect to multiple MCP servers simultaneously
• 🚀 Multiple Transport Types: Supports STDIO, SSE, and Streamable HTTP server connections
• 📋 MCP Prompts Support: Browse, invoke, and manage prompts from MCP servers with argument collection, preview, and safe rollback
• ☁️ Ollama Cloud Support: Works seamlessly with Ollama Cloud models for tool calling, enabling access to powerful cloud-hosted models while using local MCP tools
• 🎨 Rich Terminal Interface: Interactive console UI with modern styling
• 🌊 Streaming Responses: View model outputs in real-time as they're generated
• 🛠️ Tool Management: Enable/disable specific tools or entire servers during chat sessions
• 🧑‍💻 Human-in-the-Loop (HIL): Review and approve tool executions before they run for enhanced control and safety
• 🎮 Advanced Model Configuration: Fine-tune 15+ model parameters including context window size, temperature, sampling, repetition control, and more
• 💬 System Prompt Customization: Define and edit the system prompt to control model behavior and persona
• 🧠 Context Window Control: Adjust the context window size (num_ctx) to handle longer conversations and complex tasks
• 🎨 Enhanced Tool Display: Beautiful, structured visualization of tool executions with JSON syntax highlighting
• 🧠 Context Management: Control conversation memory with configurable retention settings
• 🤔 Thinking Mode: Advanced reasoning capabilities with visible thought processes for supported models (e.g., gpt-oss, deepseek-r1, qwen3, etc.)
• 🗣️ Cross-Language Support: Seamlessly work with both Python and JavaScript MCP servers
• 📜 History Management: View full conversation history, export to JSON for backup/analysis, and import previous sessions for continuity
• 🔍 Auto-Discovery: Automatically find and use Claude's existing MCP server configurations
• 🔁 Dynamic Model Switching: Switch between any installed Ollama model without restarting
• 💾 Configuration Persistence: Save and load tool preferences and model settings between sessions
• 🔄 Server Reloading: Hot-reload MCP servers during development without restarting the client
• ✨ Fuzzy Autocomplete: Interactive, arrow-key command autocomplete with descriptions
• 🏷️ Dynamic Prompt: Shows current model, thinking mode, and enabled tools
• 📊 Performance Metrics: Detailed model performance data after each query, including duration timings and token counts
• 🔌 Plug-and-Play: Works immediately with standard MCP-compliant tool servers
• 🔔 Update Notifications: Automatically detects when a new version is available
• 🖥️ Modern CLI with Typer: Grouped options, shell autocompletion, and improved help output
• ⏹️ Abort Generation: You can abort model generation at any time by pressing 'a' during response streaming

Requirements

• Python 3.10+ (Installation guide)
• Ollama running locally (Installation guide)
• UV package manager (Installation guide)

Quick Start

Option 1: Install with pip and run

pip install --upgrade ollmcp
ollmcp

Option 2: One-step install and run

uvx ollmcp

Option 3: Install from source and run using virtual environment

git clone https://github.com/jonigl/mcp-client-for-ollama.git
cd mcp-client-for-ollama
uv venv && source .venv/bin/activate
uv pip install .
uv run -m mcp_client_for_ollama

Usage

Run with default settings:

ollmcp

If you don't provide any options, the client will use auto-discovery mode to find MCP servers from Claude's configuration.

Command-line Arguments

[!TIP] The CLI now uses Typer for a modern experience: grouped options, rich help, and built-in shell autocompletion. Advanced users can use short flags for faster commands. To enable autocompletion, run:

ollmcp --install-completion

Then restart your shell or follow the printed instructions.

MCP Server Configuration:

• --mcp-server, -s: Path to one or more MCP server scripts (.py or .js). Can be specified multiple times.
• --mcp-server-url, -u: URL to one or more SSE or Streamable HTTP MCP servers. Can be specified multiple times. See Common MCP endpoint paths for typical endpoints.
• --servers-json, -j: Path to a JSON file with server configurations. See Server Configuration Format for details.
• --auto-discovery, -a: Auto-discover servers from Claude's default config file (default behavior if no other options provided).

[!TIP] Claude's configuration file is typically located at: ~/Library/Application Support/Claude/claude_desktop_config.json

Ollama Configuration:

• --model, -m MODEL: Ollama model to use. Default: qwen2.5:7b
• --host, -H HOST: Ollama host URL. Default: http://localhost:11434

General Options:

• --version, -v: Show version and exit
• --help, -h: Show help message and exit
• --install-completion: Install shell autocompletion scripts for the client
• --show-completion: Show available shell completion options

Usage Examples

Simplest way to run the client:

ollmcp

[!TIP] This will automatically discover and connect to any MCP servers configured in Claude's settings and use the default model qwen2.5:7b or the model specified in your configuration file.

Connect to a single server:

ollmcp --mcp-server /path/to/weather.py --model llama3.2:3b
# Or using short flags:
ollmcp -s /path/to/weather.py -m llama3.2:3b

Connect to multiple servers:

ollmcp --mcp-server /path/to/weather.py --mcp-server /path/to/filesystem.js
# Or using short flags:
ollmcp -s /path/to/weather.py -s /path/to/filesystem.js

[!TIP] If model is not specified, the default model qwen2.5:7b will be used or the model specified in your configuration file.

Use a JSON configuration file:

ollmcp --servers-json /path/to/servers.json --model llama3.2:1b
# Or using short flags:
ollmcp -j /path/to/servers.json -m llama3.2:1b

[!TIP] See the Server Configuration Format section for details on how to structure the JSON file.

Use a custom Ollama host:

ollmcp --host http://localhost:22545 --servers-json /path/to/servers