# Mcp Client For Ollama > Harness the power of local LLMs with this TUI MCP Client for Ollama. Featuring all core MCP primitives (tools, prompts, resources), agent mode, multi-server, model switching, streaming responses, human-in-the-loop, thinking mode, model params config, system prompts, and saved preferences. - **Type:** MCP server - **Install:** `agentstack add mcp-jonigl-mcp-client-for-ollama` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [jonigl](https://agentstack.voostack.com/s/jonigl) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [jonigl](https://github.com/jonigl) - **Source:** https://github.com/jonigl/mcp-client-for-ollama ## Install ```sh agentstack add mcp-jonigl-mcp-client-for-ollama ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About A simple yet powerful Python client for interacting with Model Context Protocol (MCP) servers using Ollama, allowing you to harness local LLMs for advanced tool execution. --- # MCP Client for Ollama (ollmcp) [](https://www.python.org/downloads/) [](https://pypi.org/project/ollmcp/) [](https://pypi.org/project/mcp-client-for-ollama/) [](https://github.com/jonigl/mcp-client-for-ollama/actions/workflows/ci.yml) đŸŽĨ Watch this demo as an Asciinema recording ## Table of Contents - [Overview](#overview) - [Features](#features) - [Requirements](#requirements) - [Quick Start](#quick-start) - [Installation options](#installation-options) - ✨**NEW** [Managing MCP Servers via CLI](#managing-mcp-servers-via-cli) - [Command-line Arguments](#command-line-arguments) - [Usage Examples](#usage-examples) - [How Tool Calls Work](#how-tool-calls-work) - ✨**NEW** [Agent Mode](#agent-mode) - [Interactive Commands](#interactive-commands) - ✨**NEW** [Answer Display Modes](#answer-display-modes) - ✨**NEW** [Input Mode](#input-mode) - [MCP Tools](#mcp-tools) - [Model Selection](#model-selection) - [Advanced Model Configuration](#advanced-model-configuration) - [Server Reloading for Development](#server-reloading-for-development) - [Human-in-the-Loop (HIL) Tool Execution](#human-in-the-loop-hil-tool-execution) - ✨**NEW** [MCP Prompts](#mcp-prompts) - ✨**NEW** [MCP Resources](#mcp-resources) - [Performance Metrics](#performance-metrics) - ✨**NEW** [History Management](#history-management) - [Autocomplete and Prompt Features](#autocomplete-and-prompt-features) - [Configuration Management](#configuration-management) - [Server Configuration Format](#server-configuration-format) - [Tips: Where to Put MCP Server Configs and a Working Example](#tips-where-to-put-mcp-server-configs-and-a-working-example) - [Compatible Models](#compatible-models) - [Ollama Cloud Models](#ollama-cloud-models) - [Where Can I Find More MCP Servers?](#where-can-i-find-more-mcp-servers) - [Related Projects](#related-projects) - [License](#license) - [Acknowledgments](#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 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](https://www.python.org/downloads/)) - **Ollama** running locally ([Installation guide](https://ollama.com/download)) - After installation, run `ollama list` to see available models. If no models are installed, you can pull one using `ollama pull `. For example, `ollama pull gemma4:latest`. - **UV package manager** ([Installation guide](https://github.com/astral-sh/uv)) ## Quick Start Install `ollmcp` via pip, add an MCP server, and run the client: ```bash # Install ollmcp 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 ollmcp ``` ## Installation Options **Option 1:** Install with pip and run ```bash pip install --upgrade ollmcp ollmcp ``` **Option 2:** Only run without installing (requires `uv` package manager) ```bash uvx ollmcp ``` **Option 3:** Install from source and run using virtual environment ```bash 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 ``` ## Managing MCP Servers via CLI ollmcp can manage its own MCP server configurations directly from the command line, similar to `claude mcp`: ```bash # Remote servers (Streamable HTTP or SSE) ollmcp mcp add --transport http ollmcp mcp add --transport sse # Local stdio servers - everything after `--` is the command to run ollmcp mcp add [options] -- [args...] # List configured servers ollmcp mcp list # Remove a server ollmcp mcp remove # For more details on options and usage, run: ollmcp mcp --help ollmcp mcp add --help ``` **Examples:** > [!TIP] > Once you have added some servers, simply running `ollmcp` will connect to them automatically. ```bash ollmcp mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer $YOUR_GITHUB_PAT" ollmcp mcp add --transport stdio playwright npx @playwright/mcp@latest ollmcp mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /allowed-dir1 ~/allowed-dir2 # stdio transport by default ollmcp mcp add --env API_KEY=YOUR_KEY --transport sse my-sse-server http://localhost:8000/sse ``` ### mcp add options - `--transport`, `-t`: `stdio` (default), `sse`, or `http`. - `--header`, `-H`: HTTP header as `"Name: Value"` for `sse`/`http` servers. Repeatable. - `--env`, `-e`: Environment variable as `KEY=value` for `stdio` servers. Repeatable. - `--scope`, `-s`: Where to store the server (see scopes below). Default: `local`. ### Scopes | Scope | Loads in | Shared with team | Stored in | |-----------|-----------------------|-------------------|-----------| | `local` | Current project only | No | `~/.config/ollmcp/mcp.local.json` (keyed by project path) | | `project` | Current project only | Yes (via VCS) | `.mcp.json` in the project root | | `user` | All your projects | No | `~/.config/ollmcp/mcp.json` | The `project` scope writes a standard `.mcp.json` file at your project root, compatible with Claude Code and other MCP-aware tools. If the same server name exists in multiple scopes, precedence is `local` > `project` > `user`. > [!NOTE] > Servers added via `ollmcp mcp add` are always loaded as the base layer. Any flags (`--mcp-server`, `--mcp-server-url`, `--servers-json`, `--claude-desktop`) add on top. To include servers from Claude Desktop, pass `--claude-desktop` explicitly. > > If a server with the same name is also provided via one of those flags, both connections are currently opened, but only one is kept active under that name — avoid reusing a registry server's name in `--mcp-server`/`--mcp-server-url`/`--servers-json`/`--claude-desktop`. ### 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: > > ```bash > 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](#common-mcp-endpoint-paths) for typical endpoints. - `--servers-json`, `-j`: Path to a JSON file with server configurations. See [Server Configuration Format](#server-configuration-format) for details. - `--claude-desktop`: Load servers from Claude Desktop's config file (`~/Library/Application Support/Claude/claude_desktop_config.json`). Merged with servers added via `ollmcp mcp add` and any other flags. > [!IMPORTANT] > **Breaking change:** `--auto-discovery` / `-a` has been replaced by `--claude-desktop`. Additionally, servers added via `ollmcp mcp add` are now always loaded automatically — they are no longer a fallback that disappears when other flags are used. Claude Desktop servers are never loaded automatically; use `--claude-desktop` to include them. #### Ollama Configuration: - `--model`, `-m` MODEL: Ollama model to use. Default: your saved configuration's model if set, otherwise the first model available in Ollama - `--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: ```bash ollmcp ``` > [!TIP] > This connects to all servers registered via `ollmcp mcp add` and uses the model from your saved configuration file, or the first available model in Ollama if none is saved. Pass `--claude-desktop` to also include servers from Claude Desktop's config. Connect to a single server: ```bash 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: ```bash 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 model from your saved configuration file is used; otherwise the first available model in Ollama is selected automatically (you'll be told how to pull one if none are installed). Use a JSON configuration file: ```bash 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](#server-configuration-format) section for details on how to structure the JSON file. Use a custom Ollama host: ```bash ollmcp --host http://localhost:22545 --servers-json /path/to/servers.json # Or using short flags: ollmcp -H http://localhost:22545 -j /path/to/servers.json ``` Connect to SSE or Streamable HTTP servers by URL: ```bash ollmcp --mcp-server-url http://localhost:8000/sse --model qwen2.5:latest # Or using short flags: ollmcp -u http://localhost:8000/sse -m qwen2.5:latest ``` Connect to multiple URL servers: ```bash ollmcp --mcp-server-url http://localhost:8000/sse --mcp-server-url http://localhost:9000/mcp # Or using short flags: ollmcp -u http://localhost:8000/sse -u http://localhost:9000/mcp ``` Mix local scripts and URL servers: ```bash ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --model qwen3:1.7b # Or using short flags: ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp -m qwen3:1.7b ``` Include Claude Desktop servers alongside other sources: ```bash ollmcp --mcp-server /path/to/weather.py --mcp-server-url http://localhost:8000/mcp --claude-desktop # Or using short flags: ollmcp -s /path/to/weather.py -u http://localhost:8000/mcp --claude-desktop ``` ## Interactive Commands During chat, use these commands: > [!IMPORTANT] > **NEW:** Built-in interactive commands now require a leading `/`. > - Use `/help`, `/model`, `/tools`, `/prompts`, etc. > - Bare command names like `help` or `model` are no longer executed as commands. > - Prompt invocations also use `/`, with `/server:prompt_name` recommended to avoid collisions. | Command | Shortcut | Description | |------------------|------------------|-----------------------------------------------------| | `abort` | `a` | While model is generating, abort the current response generation | | `/clear` | `/cc` | Clear conversation history and context | | `/cls` | `/clear-screen` | Clear the terminal screen | | `/context` | `/c` | Toggle context retention | | `/context-info` | `/ci` | Display context statistics | | `/export-history`| `/eh` | Export chat history to a JSON file | | `/full-history` | `/fh` | Display all conversation history | | `/help` | `/h` | Display help and available commands | | `/import-history`| `/ih` | Import chat history from a JSON file | | `/human-in-the-loop` | `/hil` | Toggle Human-in-the-Loop confirmations for tool execution | | `/load-config` | `/lc` | Load tool and model configuration from a file â€Ļ ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [jonigl](https://github.com/jonigl) - **Source:** [jonigl/mcp-client-for-ollama](https://github.com/jonigl/mcp-client-for-ollama) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-jonigl-mcp-client-for-ollama - Seller: https://agentstack.voostack.com/s/jonigl - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.