MCP Client for Ollama (ollmcp)
Table of Contents
- Overview
- Features
- Requirements
- Quick Start
- Usage
- Interactive Commands
- Autocomplete and Prompt Features
- Configuration Management
- Server Configuration Format
- Compatible Models
- Where Can I Find More MCP Servers?
- Related Projects
- License
- Acknowledgments
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
- 📦 MCP Resources Support: Browse and read contextual data from MCP servers including files, documents, and structured data
- ☁️ 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
- 📝 Answer Display Modes: Switch between Plain, Markdown, or Both response views while streaming
- 🛠️ 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.)
- 🖼️ Vision Tool Support: Images returned by tools are automatically forwarded to vision-capable models
- 🗣️ 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-discoverymode to find MCP servers from Claude's configuration.
Command-line Arguments
[!TIP] The CLI now uses
Typerfor 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-completionThen 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,-mMODEL: Ollama model to use. Default:qwen2.5:7b--host,-HHOST: 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:7bor 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:7bwill be used or the model specified in your config