MCP Client for Ollama (ollmcp)
Table of Contents
- Overview
- Features
- Requirements
- Quick Start
- Installation Options
- Troubleshooting
- ✨NEW Managing MCP Servers via CLI
- Interactive Commands
- Autocomplete and Prompt Features
- Configuration Management
- Server Configuration Format
- Compatible Models
- Where Can I Find More MCP Servers?
- Related Projects
- Security
- License
- Acknowledgments
Overview
MCP Client for Ollama (ollmcp) is a modern, interactive terminal application (TUI) built for harness engineering, connecting local Ollama LLMs to one or more Model Context Protocol (MCP) servers. By fully supporting the core MCP primitives (tools, prompts, and resources), it provides a controlled terminal space where you steer, and the agent executes. With a rich, user-friendly interface, it lets you safely manage your setup in real time with no coding required. Whether you're building, testing, or exploring, this client streamlines your workflow with features like fuzzy autocomplete, advanced model configuration, MCP server hot-reloading for rapid development, and strict Human-in-the-Loop safety controls.
Features
- 🤖 Agent Mode: Iterative tool execution when models request multiple tool calls, with a configurable loop limit and interactive choices when the limit is reached (continue, wrap up, or abort)
- 🌐 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
- 🌍 Multiple LLM Providers: Use Ollama (default) or OpenAI-compatible providers (OpenAI, OpenRouter, DeepSeek, etc.), with connection settings remembered per provider
- 🎨 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, Both, or Markdown (blocks) 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.)
- 💪 Reasoning Effort Levels: Set reasoning effort to auto, minimal, low, medium, high, or xhigh for supported models
- 🖼️ 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.11+ (Installation guide)
- Ollama running locally (Installation guide)
- After installation, run
ollama listto see available models. If no models are installed, you can pull one usingollama pull <model_name>. For example,ollama pull gemma4:latest.
- After installation, run
- UV package manager (Installation guide)
Quick Start
Install ollmcp via pip, add an MCP server, and run the client:
# Install ollmcp via uv
uv tool install --upgrade ollmcp
# or via pip
pip install --upgrade ollmcp
# Add an MCP server (example: playwright stdio server)
ollmcp mcp add playwright -- npx @playwright/mcp@latest
# Run the client (check optional flags with `ollmcp --help`)
ollmcp # once running, use /help for interactive commands
Installation Options
Option 1: Install with uv and run (recommended)
uv tool install --upgrade ollmcp
ollmcp
Option 2: Install with pip and run
pip install --upgrade ollmcp
ollmcp
Option 3: Only run without installing (requires uv package manager)
uvx ollmcp
Option 4: 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 run -m mcp_client_for_ollama
Troubleshooting
Could not find a version that satisfies the requirement ollmcp (from versions: none)
This almost always means the Python you are using is **older than the required 3.11