The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
npx ecc-install --profile fullFair-code workflow automation platform with native AI capabilities. Combine visual building with custom code, self-host or cloud, 400+ integrations.
npx n8nAn open-source AI agent that brings the power of Gemini directly into your terminal.
npx @google/gemini-cli
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.
ollama list to see available models. If no models are installed, you can pull one using ollama pull <model_name>. For example, ollama pull gemma4:latest.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
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
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+. This is common on macOS, where the system Python (/usr/bin/python3) or the Xcode-bundled Python can be 3.9 or older. When no release matches requires-python >= 3.11, pip filters out every version and reports the misleading "from versions: none".
First check your version:
python3 --version # must be 3.11 or newer
Then install with a modern Python. The simplest option is uv, which fetches a suitable Python for you automatically:
uv tool install --upgrade ollmcp # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, make sure to use a Python 3.11+ interpreter:
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp
Take a look at the Installation Options.
error: externally-managed-environment (PEP 668)On recent Debian/Ubuntu (Python 3.12+), the system pip is intentionally locked to protect OS-managed packages, so pip install ollmcp is blocked. This is a system policy (PEP 668), not an issue with ollmcp. Install it into an isolated environment instead:
uv tool install --upgrade ollmcp # recommended, installs the CLI in an isolated environment
# or, if you prefer pip, use a virtual environment:
python3.11 -m venv ollmcp-env
source ollmcp-env/bin/activate
python3.11 -m pip install --upgrade ollmcp
# Then run the client:
ollmcp
Take a look at the Installation Options.
[!WARNING] Avoid
pip install --break-system-packages ollmcp. It works, but it installs into the system Python and can break packages your OS depends on.
ollmcp can manage its own MCP server configurations directly from the command line, similar to claude mcp:
# Remote servers (Streamable HTTP or SSE)
ollmcp mcp add --transport http <name> <url>
ollmcp mcp add --transport sse <name> <url>
# Local stdio servers - everything after `--` is the command to run
ollmcp mcp add [options] <name> -- <command> [args...]
# List configured servers
ollmcp mcp list
# Remove a server
ollmcp mcp remove <name>
# 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
ollmcpwill connect to them automatically.
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
--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.| 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 addare 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-desktopexplicitly.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.
[!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, -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.--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/-ahas been replaced by--claude-desktop. Additionally, servers added viaollmcp mcp addare 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-desktopto include them.
--model, -m MODEL: Model to use. Default: your saved configuration's model if set, otherwise the first model available in Ollama--provider, -p PROVIDER: LLM provider to use (e.g. ollama, openai, openrouter, deepseek). Default: ollama--host, -H HOST: LLM host / API base URL. Defaults to Ollama's http://localhost:11434 for the ollama provider, or the provider's own default endpoint otherwise.--api-key, -k KEY: API key for the LLM provider. Also read from the $OLLMCP_API_KEY environment variable, which is provider-agnostic (it applies to whichever provider you select with --provider). Keys passed via $OLLMCP_API_KEY are never written to the config file; only keys passed with --api-key are saved. Not needed for ollama.[!NOTE] Currently supported providers:
ollama,openai, and any OpenAI-compatible provider (openrouter,deepseek,perplexity, etc.). More providers coming soon.
--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[!WARNING] Non-Ollama providers are experimental. Support for providers other than Ollama was added recently and is still being stabilized, not everything may work correctly yet.
ollmcp works with Ollama plus any OpenAI-compatible provider that any-llm exposes. Select one with --provider. Provide the key with --api-key or $OLLMCP_API_KEY (both work for any selected provider) or via the provider's own environment variable shown below. $OLLMCP_API_KEY and the provider-native env vars are never written to disk; only a key passed with --api-key is saved to the config.
Provider (--provider) | API key env var |
|---|---|
ollama (default) | - (local) |
azureopenai | AZURE_OPENAI_API_KEY |
dashscope | DASHSCOPE_API_KEY |
databricks | DATABRICKS_TOKEN |
deepinfra | DEEPINFRA_API_KEY |
deepseek | DEEPSEEK_API_KEY |
[!NOTE] Local OpenAI-compatible servers (
ollama,llamacpp,llamafile,lmstudio,vllm) typically run without an API key, point ollmcp at them with--host. Providers any-llm offers that are not OpenAI-compatible (e.g.anthropic,gemini,mistral,groq,cohere) are not supported yet.
[!WARNING] Capability detection limitation: ollmcp only reads real per-model capabilities (
tools,vision,thinking) from Ollama. For every non-Ollama provider, all three capabilities are currently assumed available and shown as such in the model list and badges, so a model may be reported as supporting tools, vision, or thinking even when it doesn't. If a model lacks a capability, the provider's API will return an error when you try to use it.
For the selected provider, ollmcp resolves the API key in this order, from highest to lowest precedence:
--api-key / -k flag.$OLLMCP_API_KEY environment variable (provider-agnostic, applies to whichever provider you selected with --provider).~/.config/ollmcp/config.json (present only if it was once passed via --api-key).OPENAI_API_KEY, OPENROUTER_API_KEY).[!WARNING] A saved per-provider key (3) takes precedence over the provider's native environment variable (4). So if you previously saved a wrong or expired key, setting
OPENAI_API_KEY(or the equivalent) alone will not override it. To fix it, either pass the correct key with--api-key, or remove the staleapiKeyfrom that provider's profile in~/.config/ollmcp/config.json.
Simplest way to run the client:
ollmcp
[!TIP] This connects to all servers registered via
ollmcp mcp addand uses the model from your saved configuration file, or the first available model in Ollama if none is saved. Pass--claude-desktopto also include servers from Claude Desktop's config.
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
--modelis 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:
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.json
# Or using short flags:
ollmcp -H http://localhost:22545 -j /path/to/servers.json
Use a different LLM provider (OpenAI or any OpenAI-compatible API):
ollmcp --provider openai --api-key $OPENAI_API_KEY --model gpt-5.5
# OpenAI-compatible providers (e.g. OpenRouter, DeepSeek); override the endpoint with --host if needed:
ollmcp --provider openrouter --api-key $OPENROUTER_API_KEY -m openrouter/free
[!TIP] Provider settings (model, host, API key) are remembered per provider. Once saved with
/save-config, plainollmcpresumes your last-used provider. See Configuration Management for details.
Connect to SSE or Streamable HTTP servers by URL:
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:
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:
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:
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
Some models may request multiple tool calls in a single conversation. The client supports an Agent Mode that allows for iterative tool execution:
/loop-limit (/ll) command7 to prevent infinite loopsInstead of silently stopping, the client pauses and asks you how to proceed:
| Choice | Key | Description |
|---|---|---|
| Continue | c (default) | Grant another batch of iterations (same size as the current limit) |
| Number | n | Choose exactly how many more iterations to allow |
| Unlimited | u | Remove the cap and run until the model stops requesting tools |
| Wrap up | w | Ask the model to summarise what it gathered so far and produce a final answer — preserves all tool results collected before the limit |
| Abort | a | Discard the turn entirely (nothing saved to history) |
[!NOTE] If you want to prevent using Agent Mode, simply set the loop limit to
1.
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
helpormodelare no longer executed as commands.- Prompt invocations also use
/, with/server:prompt_namerecommended 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 |
The tool and server selection interface allows you to enable or disable specific tools:
1,3,5) to toggle specific tools5-8) to toggle multiple consecutive toolsS1) to toggle all tools in a specific servera or all - Enable all toolsn or none - Disable all toolsd or desc - Show/hide tool descriptionsj or json - Show detailed tool JSON schemas on enabled tools for debugging purposess or save - Save changes and return to chatq or quit - Cancel changes and return to chatMCP Prompts provide reusable, server-defined conversation starters and context templates. Servers can expose prompts with descriptions, required arguments, and pre-formatted messages that help you quickly start specific types of conversations or inject structured context into your chat.
/server:prompt_name recommended)/ to see prompt suggestions with fuzzy matchingBrowse Available Prompts:
/prompts # or '/pr'
This displays all prompts grouped by server, showing their names, required arguments, and descriptions.
Invoke a Prompt:
/server:prompt_name
For example, if a server named docs provides a "summarize" prompt:
/docs:summarize
If a prompt name is unique across connected servers, you can use the short form:
/summarize
If multiple servers expose the same prompt name, the client will ask you to use the qualified form and suggest valid /server:prompt_name options.
Autocomplete:
/ to see all available prompts with descriptions[!TIP] Prompts are discovered automatically when you connect to MCP servers. If a server supports prompts, they'll be available immediately in the
promptslist and autocomplete.
Workflow:
/server:prompt_name (recommended) or select from autocompleteExample:
[!WARNING] Content Type Limitations: MCP Prompts currently support text content only. The following content types are not yet supported and will be automatically skipped:
- 🖼️ Images - Image content in prompts
- 🎵 Audio - Audio content in prompts
- 📦 Resources - Embedded resource content
MCP Resources provide access to contextual data exposed by MCP servers-files, documents, structured data, and more. Servers can expose resources with metadata (name, description, MIME type) that you can browse and read into your conversation context.
@uri syntax to read resource content, standalone or inline within a queryimage/*) are automatically forwarded as base64 images to vision-capable models@ to see available resource and template suggestions with fuzzy matchingBrowse Available Resources:
/resources # or '/res'
This displays all resources and templates grouped by server, showing URIs, names, MIME types, and descriptions. Binary resources are marked with a [binary] tag and templates with a [template] tag.
Read a Resource:
@<uri>
For example, to read a file resource:
@file:///path/to/document.md
There are two ways to use @uri:
1. Standalone (buffer then query): Type @uri on its own. The resource is fetched and buffered. Then type your query on the next prompt. The resource content is injected as context automatically.
2. Inline (single turn): Include @uri anywhere inside your query text. The resource is fetched and the query is processed immediately in one step.
Standalone example:
qwen3/show-thinking/6-tools❯ @server://info
✅ Read resource 'get_server_info' (197 chars)
Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.
1 resource(s) buffered. Type your query, or include @another_uri inline.
qwen3/show-thinking/6-tools❯ Next question here
Inline example:
qwen3/show-thinking/6-tools❯ summarize the key features from @server://info
✅ Read resource 'get_server_info' (197 chars)
Preview:
This is a simple MCP server with streamable HTTP transport. It supports tools for greeting, adding numbers, generating
random numbers, and calculating BMI. It also provides a BMI calculator prompt.
[model response]
[!TIP] Resources are discovered automatically when you connect to MCP servers. If a server supports resources, they'll be available immediately in the
resourceslist and@autocomplete.
[!NOTE] 🖼️ Images (
image/*) are supported, they are passed directly to vision-capable models as base64 data. Binary Content: The following resource types are not supported as context and will be skipped with an informative message:
- 🎵 Audio -
audio/*MIME types- 📹 Video -
video/*MIME types- 📄 PDFs -
application/pdf- 🗜️ Archives -
application/zip,application/octet-stream
The /display-mode (/dm) command lets you choose how model answers are shown while they stream:
Use /display-mode or /dm during chat to open the interactive picker.
Why you might switch modes:
[!TIP] Your selected display mode is saved with
/save-configand restored with/load-config, so you can keep different viewing preferences for different workflows.
The /input-mode (/im) command controls how you write chat messages:
Use /input-mode or /im during chat to open the interactive picker.
[!IMPORTANT] Multiline send shortcuts can vary by terminal emulator and OS keyboard handling. This client relies on Esc then Enter as the portable submit shortcut in multiline mode. Shift+Enter and Meta+Enter may work in some terminals, but they are not guaranteed.
The model selection interface shows all available models in your Ollama installation:
s or save - Save the model selection and return to chatq or quit - Cancel the model selection and return to chatThe /model-config (/mc) command opens the advanced model settings interface, allowing you to fine-tune how the model generates responses:
1-15 to edit settingssp to edit the system promptu1, u2, etc. to unset parameters, or uall to reset allh/help: Show parameter details and tipsundo: Revert changess/save: Apply changesq/quit: Canceltemperature: 0.0-0.3, top_p: 0.1-0.5, seed: 42temperature: 1.0+, top_p: 0.95, presence_penalty: 0.2repeat_penalty: 1.1-1.3, presence_penalty: 0.2, frequency_penalty: 0.3temperature: 0.7, top_p: 0.9, typical_p: 0.7seed: 42, temperature: 0.0num_ctx: 8192 or higher for complex conversations requiring more context[!TIP] All parameters default to unset, letting Ollama use its own optimized values. Use
helpin the config menu for details and recommendations. Changes are saved with your configuration.
Enable thinking mode with /thinking-mode (/tm) to activate extended reasoning on supported models (e.g., qwen3, deepseek-r1, Claude with extended thinking). Use /show-thinking (/st) to toggle whether the reasoning process is visible in the response.
Use /reasoning-effort (/re) to control how much reasoning effort the model applies when thinking mode is on:
| Level | Description |
|---|---|
auto | Provider's default effort (recommended for cloud) |
minimal | Fastest, least reasoning |
low | Light reasoning |
medium | Balanced — default |
high | More thorough reasoning |
xhigh | Maximum reasoning effort |
[!NOTE] Some providers or models may ignore reasoning effort settings.
The /reload-servers command (/rs) is particularly useful during MCP server development. It allows you to reload all connected servers without restarting the entire client application.
Key Benefits:
When to Use:
Simply type /reload-servers or /rs in the chat interface, and the client will:
ollmcp mcp add, server paths, config files, --claude-desktop)This feature dramatically improves the development experience when building and testing MCP servers.
The Human-in-the-Loop feature provides an additional safety layer by allowing you to review and approve tool executions before they run. This is particularly useful for:
When HIL is enabled, you'll see a confirmation prompt before each tool execution:
Example:
When prompted, you can choose from the following options:
/hil command)[!TIP] The session option is particularly useful when the model needs to execute multiple tools in sequence. Instead of confirming each one individually, you can approve all tools for the current query session, then HIL will reset automatically for the next query.
/human-in-the-loop or /hil to toggle on/off/hil command anytime to turn confirmations back onBenefits:
The Performance Metrics feature displays detailed model performance data after each query in a bordered panel. The metrics show duration timings, token counts, and generation rates directly from Ollama's response.
Displayed Metrics:
total duration: Total time spent generating the complete response (seconds)load duration: Time spent loading the model (milliseconds)prompt eval count: Number of tokens in the input promptprompt eval duration: Time spent evaluating the input prompt (milliseconds)eval count: Number of tokens generated in the responseeval duration: Time spent generating the response tokens (seconds)prompt eval rate: Speed of input prompt processing (tokens/second)eval rate: Speed of response token generation (tokens/second)Example:
/show-metrics or /sm to enable/disable metrics displayBenefits:
[!NOTE] Data Source: All metrics come directly from Ollama's response, ensuring accuracy and reliability.
The History Management feature allows you to view, export, and import your conversation history. This is useful for:
View Full History:
/full-history # or '/fh'
Displays all conversation history from the current session in a formatted view, showing both queries and responses.
Export History:
/export-history # or '/eh'
Exports your current chat history to a JSON file. You can specify a custom filename or use the default timestamp-based name (e.g., ollmcp_chat_history_2026-01-05_143022.json). Files are saved to ~/.config/ollmcp/history/ directory. The command includes file overwrite protection.
Import History:
/import-history # or '/ih'
Imports a previously exported chat history from a JSON file. The command validates the JSON structure to ensure compatibility. Imported history is added to your current conversation context.
History Storage:
~/.config/ollmcp/history/ollmcp_chat_history_YYYY-MM-DD_HHMMSS.jsonBenefits:
[!TIP] When exporting, if you don't provide a filename, the system automatically generates a timestamped filename to prevent accidental overwrites.
ollmcp --install-completion and follow the instructions for your shell/)/ to trigger prompt autocomplete/server:prompt_nameThe chat prompt now gives you clear, contextual information at a glance:
Example prompt:
qwen3/show-thinking/12-tools❯
qwen3 Model name/show-thinking Thinking mode indicator (if enabled, otherwise /thinking or omitted)/12-tools Number of tools enabled (or /1-tool for singular)❯ Prompt symbolThis makes it easy to see your current context before entering a query.
[!TIP] Type
/after the prompt symbol to see autocomplete suggestions for available MCP prompts.
[!TIP] Running
ollmcpwith no flags automatically loads the default configuration from~/.config/ollmcp/config.jsonif it exists.
The client saves and loads your preferences between sessions:
/save-config, you can provide a name for the configuration or use the default~/.config/ollmcp/ directory~/.config/ollmcp/config.json~/.config/ollmcp/{name}.jsonConnection settings are stored per provider, so switching providers never reuses another provider's model, host, or API key. Each provider keeps its own:
The configuration also records a defaultProvider. When you run ollmcp with no --provider flag, it loads that provider's profile; a fresh install starts on ollama. Each time you /save-config, the provider you're currently using becomes the new default, so running plain ollmcp resumes wherever you left off. Pass --provider <name> at any time to switch to (and load) a different provider's profile, and --model / --host / --api-key override the saved values for that run.
[!NOTE] Only a key passed with
--api-keyis stored, in plain text, in~/.config/ollmcp/config.json. Keys provided through the$OLLMCP_API_KEYenvironment variable or a provider's native environment variable (for exampleOPENROUTER_API_KEY) are never written to disk, use one of those if you don't want your key persisted.
The following settings are shared across all providers:
Example ~/.config/ollmcp/config.json:
{
"defaultProvider": "openai",
"providers": {
"ollama": { "host": "http://localhost:11434", "model": "qwen3:1.7b", "apiKey": "" },
"openai": { "host": "", "model": "gpt-5.5", "apiKey": "sk-..." }
},
"enabledTools": {},
"modelConfig": {},
"...": "shared settings"
}
[!TIP] Older flat config files (with top-level
host/model/provider/apiKey) are migrated automatically the first time you run this version, and rewritten in the per-provider format on your next/save-config.
The JSON configuration file supports STDIO, SSE, and Streamable HTTP server types (MCP 1.10.1):
{
"mcpServers": {
"stdio-server": {
"command": "command-to-run",
"args": ["arg1", "arg2", "..."],
"env": {
"ENV_VAR1": "value1",
"ENV_VAR2": "value2"
},
"disabled": false
},
"sse-server": {
"type": "sse",
"url": "http://localhost:8000/sse",
"headers": {
"Authorization": "Bearer your-token-here"
},
"disabled": true
},
"http-server": {
"type": "streamable_http",
"url": "http://localhost:8000/mcp",
"headers": {
"X-API-Key": "your-api-key-here"
},
"disabled": false
}
}
}
[!NOTE] MCP 1.10.1 Transport Support: The client now supports the latest Streamable HTTP transport with improved performance and reliability. If you specify a URL without a type, the client will default to using Streamable HTTP transport.
A common point of confusion is where to store MCP server configuration files and how the TUI's save/load feature is used. Here's a short, practical guide that has helped other users:
/save-config / /load-config (or /sc / /lc) commands are intended to save TUI preferences like which tools you enabled, your selected model, thinking mode, display mode, and other client-side settings. They are not required to register MCP server connections with the client.mcpServers object shown above) we recommend keeping them outside the TUI config directory or in a clear subfolder, for example:~/.config/ollmcp/mcp-servers/config.json
You can then point ollmcp at that file at startup with -j / --servers-json.
[!IMPORTANT] For HTTP-based MCP servers,
"type": "http","streamable-http", and"streamable_http"are all accepted and treated the same way. Also check the Common MCP endpoint paths section below for typical endpoints.
Here a minimal working example let's say this is your ~/.config/ollmcp/mcp-servers/config.json:
{
"mcpServers": {
"github": {
"type": "streamable_http",
"url": "https://api.githubcopilot.com/mcp/",
"headers": {
"Authorization": "Bearer mytoken"
}
}
}
}
[!TIP] When using GitHub MCP server, make sure to replace
"mytoken"with your actual GitHub API token.
With that file in place you can connect using:
ollmcp -j ~/.config/ollmcp/mcp-servers/config.json
Here you can find a GitHub issue related to this common pitfall: https://github.com/jonigl/mcp-client-for-ollama/issues/112#issuecomment-3446569030
A short demo (asciicast) that should help anyone reproduce the working setup quickly. This example uses an MCP server example with streamable HTTP protocol usage:
Streamable HTTP MCP servers typically expose the MCP endpoint at /mcp (e.g., https://host/mcp), while SSE servers commonly use /sse (e.g., https://host/sse). Below is an excerpt from the MCP specification (2025-06-18):
The server MUST provide a single HTTP endpoint path (hereafter referred to as the MCP endpoint) that supports both POST and GET methods. For example, this could be a URL like https://example.com/mcp.
You can find more details in the MCP specification version 2025-06-18 - Transports.
The following Ollama models work well with tool use:
For a complete list of Ollama models with tool use capabilities, visit the official Ollama models page.
For models that can also process images returned by tools, see the Ollama vision models page.
MCP Client for Ollama now supports Ollama Cloud models, allowing you to use powerful cloud-hosted models with tool calling capabilities while leveraging your local MCP tools. Cloud models can run without a powerful local GPU, making it possible to access larger models that wouldn't fit on a personal computer.
Supported Ollama Cloud models include for example:
gpt-oss:20b-cloudgpt-oss:120b-clouddeepseek-v3.1:671b-cloudqwen3-coder:480b-cloudTo use Ollama Cloud models with this client:
First, pull the cloud model:
ollama pull gpt-oss:120b-cloud
Run the client with your chosen cloud model:
ollmcp --model gpt-oss:120b-cloud
[!NOTE] The model
deepseek-v3.1:671b-cloudonly supports tool use when thinking mode is turned off. You can toggle thinking mode inollmcpby typing either/thinking-modeor/tm.
For more information about Ollama Cloud, visit the Ollama Cloud documentation.
You can explore a collection of MCP servers in the official MCP Servers repository.
This repository contains reference implementations for the Model Context Protocol, community-built servers, and additional resources to enhance your LLM tool capabilities.
MCP servers you connect are trusted by you, and their tool/resource responses are treated as untrusted content that reaches the model. See SECURITY.md for the trust model, how indirect prompt injection is handled, and how to report a vulnerability.
This project is licensed under the MIT License - see the LICENSE file for details.
Made with ❤️ by jonigl
fireworksFIREWORKS_API_KEY |
gateway | GATEWAY_API_KEY |
inception | INCEPTION_API_KEY |
llama | LLAMA_API_KEY |
llamacpp | - (local) |
llamafile | - (local) |
lmstudio | LM_STUDIO_API_KEY |
minimax | MINIMAX_API_KEY |
moonshot | MOONSHOT_API_KEY |
mzai | ANY_LLM_KEY |
nebius | NEBIUS_API_KEY |
openai | OPENAI_API_KEY |
openrouter | OPENROUTER_API_KEY |
perplexity | PERPLEXITY_API_KEY |
portkey | PORTKEY_API_KEY |
qiniu | QINIU_API_KEY |
sambanova | SAMBANOVA_API_KEY |
vllm | VLLM_API_KEY |
zai | ZAI_API_KEY |
/hil |
| Toggle Human-in-the-Loop confirmations for tool execution |
/load-config | /lc | Load tool and model configuration from a file |
/loop-limit | /ll | Set maximum iterative tool-loop iterations (Agent Mode). Default: 7 |
/model | /m | List and select a different Ollama model |
/model-config | /mc | Configure advanced model parameters and system prompt |
/display-mode | /dm | Choose Plain, Markdown, Both, or Markdown (blocks) answer display modes |
/input-mode | /im | Choose Single-line or Multiline chat input mode |
/prompts | /pr | Browse and view all available MCP prompts |
/server:prompt_name | /prompt_name | Invoke a prompt (qualified is recommended) |
/resources | /res | Browse and view all available MCP resources |
@uri | - | Read a specific resource by URI (e.g., @server://info) |
/quit, /exit, /bye | /q, Ctrl+C, or Ctrl+D | Exit the client |
/reload-servers | /rs | Reload all MCP servers with current configuration |
/reset-config | /rc | Reset configuration to defaults (all tools enabled) |
/save-config | /sc | Save current tool and model configuration to a file |
/show-metrics | /sm | Toggle performance metrics display |
/show-thinking | /st | Toggle thinking text visibility (visible by default) |
/thinking-mode | /tm | Toggle thinking mode on supported models |
/reasoning-effort | /re | Set reasoning effort level (auto/minimal/low/medium/high/xhigh) when thinking mode is on. Default: medium |
/show-tool-execution | /ste | Toggle tool execution display visibility |
/tools | /t | Open the tool selection interface |