MCP Client for Ollama (ollmcp)

PyPI - Downloads Python 3.11+ PyPI - Python Version PyPI - Python Version CI

Table of Contents

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 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.
  • 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+. 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.

Managing MCP Servers via CLI

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 ollmcp will 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

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:

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.
  • --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.

Inference Provider Configuration:

  • --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, atlascloud, 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, atlascloud, and any OpenAI-compatible provider (openrouter, deepseek, perplexity, etc.). More providers coming soon.

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

Supported Inference Providers

[!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)
atlascloud ATLASCLOUD_API_KEY
azureopenai AZURE_OPENAI_API_KEY
dashscope DASHSCOPE_API_KEY
databricks DATABRICKS_TOKEN
deepinfra DEEPINFRA_API_KEY
deepseek DEEPSEEK_API_KEY
fireworks FIREWORKS_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

[!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.

API key resolution order

For the selected provider, ollmcp resolves the API key in this order, from highest to lowest precedence:

  1. The --api-key / -k flag.
  2. The $OLLMCP_API_KEY environment variable (provider-agnostic, applies to whichever provider you selected with --provider).
  3. The per-provider key saved in ~/.config/ollmcp/config.json (present only if it was once passed via --api-key).
  4. The provider's own native environment variable, detected by any-llm (e.g. 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 stale apiKey from that provider's profile in ~/.config/ollmcp/config.json.

Usage Examples

Simplest way to run the client:

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:

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 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, plain ollmcp resumes 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

How Tool Calls Work

  1. The client sends your query to Ollama with a list of available tools
  2. If Ollama decides to use a tool, the client:
    • Displays the tool execution with formatted arguments and syntax highlighting
    • Shows a Human-in-the-Loop confirmation prompt (if enabled) allowing you to review and approve the tool call
    • Extracts the tool name and arguments from the model response
    • Calls the appropriate MCP server with these arguments (only if approved or HIL is disabled)
    • Shows the tool response in a structured, easy-to-read format (including image and unsupported-media summaries)
    • If the tool returned images and the current model supports vision, attaches the images to the next LLM message; otherwise displays a warning
    • Sends the tool result back to Ollama
    • If in Agent Mode, repeats the process if the model requests more tool calls
  3. Finally, the client:
    • Displays the model's final response incorporating the tool results

Agent Mode

Some models may request multiple tool calls in a single conversation. The client supports an Agent Mode that allows for iterative tool execution:

  • When the model requests a tool call, the client executes it and sends the result back to the model
  • This process repeats until the model provides a final answer or reaches the configured loop limit
  • You can set the maximum number of iterations using the /loop-limit (/ll) command
  • The default loop limit is 7 to prevent infinite loops

When the loop limit is reached

Instead 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.

Agent Mode Quick Demo:

asciicast

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.

ollmcp main interface

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
/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

MCP Tools

The tool and server selection interface allows you to enable or disable specific tools:

ollmcp tool and server selection interface

  • Enter numbers separated by commas (e.g. 1,3,5) to toggle specific tools
  • Enter ranges of numbers (e.g. 5-8) to toggle multiple consecutive tools
  • Enter S + number (e.g. S1) to toggle all tools in a specific server
  • a or all - Enable all tools
  • n or none - Disable all tools
  • d or desc - Show/hide tool descriptions
  • j or json - Show detailed tool JSON schemas on enabled tools for debugging purposes
  • s or save - Save changes and return to chat
  • q or quit - Cancel changes and return to chat

MCP Prompts

MCP 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.

Features

  • 📋 Browse Prompts: View all available prompts from connected servers with descriptions and argument requirements
  • ⚡️ Quick Invocation: Use slash syntax to invoke prompts (/server:prompt_name recommended)
  • 🔤 Autocomplete: Type / to see prompt suggestions with fuzzy matching
  • 📝 Argument Collection: Interactive prompts guide you through required parameters
  • 👁️ Preview: Review prompt content before injection to ensure it fits your needs
  • 🎯 Flexible Injection: Choose to execute immediately or inject-only (add to history without triggering model)
  • 🧠 Context-Aware: Automatically adapts behavior based on whether prompt ends with user or assistant message
  • 🔄 Safe Rollback: Automatic history cleanup if you abort or encounter errors
  • 💬 Text Content: Supports text-based prompt messages (image/audio/resource support coming soon)

How to Use MCP Prompts

Browse 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:

  • Type / to see all available prompts with descriptions
  • Continue typing to filter prompts with fuzzy matching
  • Use arrow keys to navigate and press Enter to select

[!TIP] Prompts are discovered automatically when you connect to MCP servers. If a server supports prompts, they'll be available immediately in the prompts list and autocomplete.

Workflow:

  1. Type /server:prompt_name (recommended) or select from autocomplete
  2. If the prompt requires arguments, you'll be prompted to provide them
  3. Review the prompt preview showing what will be injected
  4. Choose how to use the prompt:
    • y/yes (default): Send the prompt to the model and get a response
      • For prompts ending with a user message: Uses that message as the query
      • For prompts ending with an assistant message: Adds "Please respond based on the above context." as the query
    • i/inject: Just add the prompt to conversation history without triggering the model (lets you type your own query afterward)
    • n/no: Cancel and return to chat
  5. The prompt is injected based on your choice
  6. If you abort during model generation (press 'a'), changes are automatically rolled back

Example: ollmcp prompt feature screenshot

[!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

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.

Features

  • 📋 Browse Resources: View all available resources from connected servers with URIs, names, MIME types, and descriptions
  • 📖 Read Resources: Use @uri syntax to read resource content, standalone or inline within a query
  • 📝 Text Content: Full support for text-based resources (markdown, code, logs, etc.)
  • 🖼️ Vision Image Support: Image resources (image/*) are automatically forwarded as base64 images to vision-capable models
  • 🎯 Context Injection: Resource content is buffered and injected as context alongside your next query
  • 🔍 Autocomplete: Type @ to see available resource and template suggestions with fuzzy matching
  • 🛡️ Binary Safety: Non-image binary content (audio, video, PDFs, archives) is detected and gracefully skipped with informative messages

How to Use MCP Resources

Browse 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 resources list 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

Answer Display Modes

The /display-mode (/dm) command lets you choose how model answers are shown while they stream:

  • Plain: Streams the response once as plain text with no final markdown re-render
  • ✨NEW Markdown (default): Streams formatted markdown line by line — lines above a small live tail are printed once and never redrawn, so it stays reliable even with emojis or terminal resizes
  • Both: Streams plain text first, then renders the completed response again as markdown
  • Markdown (blocks): Renders the response as markdown one block at a time, append-only each paragraph/list/table/code block prints once when it completes and is never redrawn, so it cannot duplicate lines

Use /display-mode or /dm during chat to open the interactive picker.

Why you might switch modes:

  • Plain is the least noisy option if you want minimal redraw or flicker
  • Markdown combines line-by-line streaming with coherent markdown formatting; at most the last few lines are ever redrawn, so glitches stay bounded even with emojis or resizes
  • Both gives you fast streaming feedback plus a clean final markdown rendering
  • **Ma