gem-hunter
A powerful, feature-rich command-line interface for interacting with Model Context Protocol servers. This client enables seamless communication with LLMs through integration with the CHUK Tool Processor and CHUK-LLM, providing tool usage, conversation management, and multiple operational modes.
Default Configuration: MCP CLI defaults to using Ollama with the gpt-oss reasoning model for local, privacy-focused operation without requiring API keys.
--vm flag: Enable OS-style virtual memory for conversation context management, powered by chuk-ai-session-manager--vm-budget: Control token budget for conversation events (system prompt is uncapped on top), forcing earlier eviction and page creation--vm-mode: Choose VM mode — passive (runtime-managed, default), relaxed (VM-aware conversation), or strict (model-driven paging with tools)/memory command: Visualize VM state during conversations — page table, working set utilization, eviction metrics, TLB stats (aliases: /vm, /mem)/memory page <id> --download: Export page content to local files with modality-aware extensions (.txt, .json, .png)/plan command: Create, inspect, and execute reproducible tool call graphs — create, list, show, run, delete, resume--plan-tools): The LLM autonomously creates and executes plans during conversation — no /plan command needed. It calls plan_create_and_execute when multi-step orchestration is required, and uses regular tools for simple tasks. Each step renders with real-time progress in the terminalmax_concurrency${var}, ${var.field} nested access, and template strings like "https://${api.host}/users" — type-preserving for single refs/plan resume <id>enable_replan=True)_meta.ui annotations automatically open in the browser when called--log-file flag enables rotating JSON log files (10MB, 3 backups) at DEBUG leveltool_timeout and init_timeout overrides, resolved per-server → global → defaultasyncio.Lock and copy-on-write header mutation/health command, health-check-on-failure diagnostics, optional --health-interval background polling/usage command (aliases: /tokens, /cost)/sessions)/export)--dashboard flag: Launch a real-time browser dashboard alongside chat mode/attach command: Stage files for the next message — images, text/code, and audio (aliases: /file, /image)--attach CLI flag: Attach files to the first message (repeatable: --attach img.png --attach code.py)@file: references: Mention @file:path/to/file anywhere in a message to attach itlogging only — no UI importsThe MCP CLI is built on a modular architecture with clean separation of concerns:
/usage command/attach, --attach, @file: refs, or browser uploadMCP CLI supports all providers and models from CHUK-LLM, including cutting-edge reasoning models:
| Provider | Key Models | Special Features |
|---|---|---|
| Ollama (Default) | 🧠 gpt-oss, llama3.3, llama3.2, qwen3, qwen2.5-coder, deepseek-coder, granite3.3, mistral, gemma3, phi3, codellama | Local reasoning models, privacy-focused, no API key required |
| OpenAI | 🚀 GPT-5 family (gpt-5, gpt-5-mini, gpt-5-nano), GPT-4o family, O3 series (o3, o3-mini) | Advanced reasoning, function calling, vision |
| Anthropic | 🧠 Claude 4.5 family (claude-4-5-opus, claude-4-5-sonnet), Claude 3.5 Sonnet | Enhanced reasoning, long context |
| Azure OpenAI 🏢 | Enterprise GPT-5, GPT-4 models | Private endpoints, compliance, audit logs |
| Google Gemini | Gemini 2.0 Flash, Gemini 1.5 Pro | Multimodal, fast inference |
| Groq ⚡ | Llama 3.1 models, Mixtral | Ultra-fast inference (500+ tokens/sec) |
| Perplexity 🌐 | Sonar models | Real-time web search with citations |
| IBM watsonx 🏢 | Granite, Llama models | Enterprise compliance |
| Mistral AI 🇪🇺 | Mistral Large, Medium | European, efficient models |
_meta.ui annotations automatically launch browser apps on tool call--plan-tools, the LLM autonomously decides when to plan — calls plan_create_and_execute for complex multi-step tasks, uses regular tools for simple onesresult_variable), referenced by later steps as ${var} or ${var.field}~/.mcp-cli/plans/Comprehensive documentation is available in the docs/ directory:
ollama pull gpt-ossOPENAI_API_KEY environment variable (for GPT-5, GPT-4, O3 models)ANTHROPIC_API_KEY environment variable (for Claude 4.5, Claude 3.5)AZURE_OPENAI_API_KEY and AZURE_OPENAI_ENDPOINT (for enterprise GPT-5)GEMINI_API_KEY (for Gemini models)GROQ_API_KEY (for fast Llama models)server_config.json)# macOS/Linux curl -fsSL https://ollama.ai/install.sh | sh # Or visit https://ollama.ai for other installation methods
ollama pull gpt-oss # Open-source reasoning model with thinking visibility# Using uvx (recommended) uvx mcp-cli --help # Or install from source git clone https://github.com/chrishayuk/mcp-cli cd mcp-cli pip install -e "." mcp-cli --help # Optional: Enable MCP Apps (interactive browser UIs) pip install -e ".[apps]"
# === LOCAL MODELS (No API Key Required) === # Use default reasoning model (gpt-oss) mcp-cli --server sqlite # Use other Ollama models mcp-cli --model llama3.3 # Latest Llama mcp-cli --model qwen2.5-coder # Coding-focused mcp-cli --model deepseek-coder # Another coding model mcp-cli --model granite3.3 # IBM Granite # === CLOUD PROVIDERS (API Keys Required) === # GPT-5 Family (requires OpenAI API key) mcp-cli --provider openai --model gpt-5 # Full GPT-5 with reasoning mcp-cli --provider openai --model gpt-5-mini # Efficient GPT-5 variant mcp-cli --provider openai --model gpt-5-nano # Ultra-lightweight GPT-5 # GPT-4 Family mcp-cli --provider openai --model gpt-4o # GPT-4 Optimized mcp-cli --provider openai --model gpt-4o-mini # Smaller GPT-4 # O3 Reasoning Models mcp-cli --provider openai --model o3 # O3 reasoning mcp-cli --provider openai --model o3-mini # Efficient O3 # Claude 4.5 Family (requires Anthropic API key) mcp-cli --provider anthropic --model claude-4-5-opus # Most advanced Claude mcp-cli --provider anthropic --model claude-4-5-sonnet # Balanced Claude 4.5 mcp-cli --provider anthropic --model claude-3-5-sonnet # Claude 3.5 # Enterprise Azure (requires Azure configuration) mcp-cli --provider azure_openai --model gpt-5 # Enterprise GPT-5 # Other Providers mcp-cli --provider gemini --model gemini-2.0-flash # Google Gemini mcp-cli --provider groq --model llama-3.1-70b # Fast Llama via Groq
MCP CLI defaults to:
ollama (local, no API key required)gpt-oss (open-source reasoning model with thinking visibility)Global options available for all modes and commands:
--server: Specify server(s) to connect to (comma-separated)--config-file: Path to server configuration file (default: server_config.json)--provider: LLM provider (default: ollama)--model: Specific model to use (default: gpt-oss for Ollama)--disable-filesystem: Disable filesystem access (default: enabled)--api-base: Override API endpoint URL--api-key: Override API key (not needed for Ollama)--token-backend: Override token storage backend (auto, keychain, windows, secretservice, encrypted, vault)--verbose: Enable detailed logging--quiet: Suppress non-essential output--log-file: Write debug logs to a rotating file (secrets auto-redacted)--vm: [Experimental] Enable AI virtual memory for context management--vm-budget: Token budget for conversation events in VM mode (default: 128000, on top of system prompt)--vm-mode: VM mode — passive (default), relaxed, or strict--dashboard: Launch a real-time browser dashboard UI alongside chat mode--attach: Attach files to the first message (repeatable: --attach img.png --attach code.py)--plan-tools: Enable model-driven planning — the LLM autonomously creates and executes multi-step plans--no-tools: Disable MCP tool calling entirely — chat directly with the LLM without connecting to any MCP servers# Override defaults export LLM_PROVIDER=ollama # Default provider (already the default) export LLM_MODEL=gpt-oss # Default model (already the default) # For cloud providers (optional) export OPENAI_API_KEY=sk-... # For GPT-5, GPT-4, O3 models export ANTHROPIC_API_KEY=sk-ant-... # For Claude 4.5, Claude 3.5 export AZURE_OPENAI_API_KEY=sk-... # For enterprise GPT-5 export AZURE_OPENAI_ENDPOINT=https://... export GEMINI_API_KEY=... # For Gemini models export GROQ_API_KEY=... # For Groq fast inference # Tool configuration export MCP_TOOL_TIMEOUT=120 # Tool execution timeout (seconds)
Provides a natural language interface with streaming responses and automatic tool usage:
# Default mode with Ollama/gpt-oss reasoning model (no API key needed) mcp-cli --server sqlite # See the AI's thinking process with reasoning models mcp-cli --server sqlite --model gpt-oss # Open-source reasoning mcp-cli --server sqlite --provider openai --model gpt-5 # GPT-5 reasoning mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus # Claude 4.5 reasoning # Use different local models mcp-cli --server sqlite --model llama3.3 mcp-cli --server sqlite --model qwen2.5-coder # Switch to cloud providers (requires API keys) mcp-cli chat --server sqlite --provider openai --model gpt-5 mcp-cli chat --server sqlite --provider anthropic --model claude-4-5-sonnet # Launch with real-time browser dashboard mcp-cli --server sqlite --dashboard # Attach files to the first message mcp-cli --server sqlite --attach image.png --attach data.csv
Command-driven shell interface for direct server operations:
mcp-cli interactive --server sqlite # With specific models mcp-cli interactive --server sqlite --model gpt-oss # Local reasoning mcp-cli interactive --server sqlite --provider openai --model gpt-5 # Cloud GPT-5
Unix-friendly interface for automation and scripting:
# Process text with reasoning models mcp-cli cmd --server sqlite --model gpt-oss --prompt "Think through this step by step" --input data.txt # Use GPT-5 for complex reasoning mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Analyze this data" --input data.txt # Execute tools directly mcp-cli cmd --server sqlite --tool list_tables --output tables.json # Pipeline-friendly processing echo "SELECT * FROM users LIMIT 5" | mcp-cli cmd --server sqlite --tool read_query --input -
Execute individual commands without entering interactive mode:
# List available tools mcp-cli tools --server sqlite # Show provider configuration mcp-cli provider list # Show available models for current provider mcp-cli models # Show models for specific provider mcp-cli models openai # Shows GPT-5, GPT-4, O3 models mcp-cli models anthropic # Shows Claude 4.5, Claude 3.5 models mcp-cli models ollama # Shows gpt-oss, llama3.3, etc. # Ping servers mcp-cli ping --server sqlite # List resources mcp-cli resources --server sqlite # UI Theme Management mcp-cli theme # Show current theme and list available mcp-cli theme dark # Switch to dark theme mcp-cli theme --select # Interactive theme selector mcp-cli theme --list # List all available themes # Token Storage Management mcp-cli token backends # Show available storage backends mcp-cli --token-backend encrypted token list # Use specific backend
MCP Apps allow tool servers to provide interactive HTML UIs that render in your browser. When a tool has a _meta.ui annotation pointing to a UI resource, mcp-cli automatically launches a local web server and opens the app in your browser.
# Install the apps extra (adds websockets dependency) pip install "mcp-cli[apps]"
_meta.ui metadata (e.g., show_chart, show_table)# Connect to a server with app-enabled tools mcp-cli --server view_demo # In chat, ask for something visual: > Show me the sales data as a chart # Browser opens automatically with an interactive chart # The /tools command shows which tools have app UIs (APP column) > /tools
See MCP Apps Documentation for the full guide.
Chat mode provides the most advanced interface with streaming responses and intelligent tool usage.
# Simple startup with default reasoning model (gpt-oss) mcp-cli --server sqlite # Multiple servers mcp-cli --server sqlite,filesystem # With advanced reasoning models mcp-cli --server sqlite --provider openai --model gpt-5 mcp-cli --server sqlite --provider anthropic --model claude-4-5-opus
/provider # Show current configuration (default: ollama) /provider list # List all providers /provider config # Show detailed configuration /provider diagnostic # Test provider connectivity /provider set ollama api_base http://localhost:11434 # Configure Ollama endpoint /provider openai # Switch to OpenAI (requires API key) /provider anthropic # Switch to Anthropic (requires API key) /provider openai gpt-5 # Switch to OpenAI GPT-5 # Custom Provider Management /provider custom # List custom providers /provider add localai http://localhost:8080/v1 gpt-4 # Add custom provider /provider remove localai # Remove custom provider /model # Show current model (default: gpt-oss) /model llama3.3 # Switch to different Ollama model /model gpt-5 # Switch to GPT-5 (if using OpenAI) /model claude-4-5-opus # Switch to Claude 4.5 (if using Anthropic) /models # List available models for current provider
/tools # List available tools /tools --all # Show detailed tool information /tools --raw # Show raw JSON definitions /tools call # Interactive tool execution /toolhistory # Show tool execution history /th -n 5 # Last 5 tool calls /th 3 # Details for call #3 /th --json # Full history as JSON
/server # List all configured servers /server list # List servers (alias) /server list all # Include disabled servers # Add servers at runtime (persists in ~/.mcp-cli/preferences.json) /server add <name> stdio <command> [args...] /server add sqlite stdio uvx mcp-server-sqlite --db-path test.db /server add playwright stdio npx @playwright/mcp@latest /server add time stdio uvx mcp-server-time /server add fs stdio npx @modelcontextprotocol/server-filesystem /path/to/dir # HTTP/SSE server examples with authentication /server add github --transport http --header "Authorization: Bearer ghp_token" -- https://api.github.com/mcp /server add myapi --transport http --env API_KEY=secret -- https://api.example.com/mcp /server add events --transport sse -- https://events.example.com/sse # Manage server state /server enable <name> # Enable a disabled server /server disable <name> # Disable without removing /server remove <name> # Remove user-added server /server ping <name> # Test server connectivity # Server details /server <name> # Show server configuration details
Note: Servers added via /server add are stored in ~/.mcp-cli/preferences.json and persist across sessions. Project servers remain in server_config.json.
/attach image.png # Stage an image for the next message /attach code.py # Stage a text file /attach list # Show currently staged files /attach clear # Clear staged files /file data.csv # Alias for /attach /image screenshot.heic # Alias for /attach # Inline file references (in any message) @file:screenshot.png describe what you see @file:data.csv summarize this data # Image URLs are auto-detected https://example.com/photo.jpg what is in this image?
/conversation # Show conversation history /ch -n 10 # Last 10 messages /ch 5 # Details for message #5 /ch --json # Full history as JSON /save conversation.json # Save conversation to file /compact # Summarize conversation /clear # Clear conversation history /cls # Clear screen only
/theme # Interactive theme selector with preview /theme dark # Switch to dark theme /theme monokai # Switch to monokai theme # Available themes: default, dark, light, minimal, terminal, monokai, dracula, solarized # Themes are persisted across sessions
/token # List all stored tokens /token list # List all tokens explicitly /token set <name> # Store a bearer token /token get <name> # Get token details /token delete <name> # Delete a token /token clear # Clear all tokens (with confirmation) /token backends # Show available storage backends # Examples /token set my-api # Prompts for token value (secure) /token get notion --oauth # Get OAuth token for Notion server /token list --api-keys # List only provider API keys
Token Storage Backends: MCP CLI supports multiple secure token storage backends:
Override the default backend with --token-backend:
# Use encrypted file storage instead of keychain mcp-cli --token-backend encrypted token list # Use vault for enterprise environments mcp-cli --token-backend vault token list
See Token Management Guide for comprehensive documentation.
/verbose # Toggle verbose/compact display (Default: Enabled) /confirm # Toggle tool call confirmation (Default: Enabled) /interrupt # Stop running operations /server # Manage MCP servers (see Server Management above) /help # S
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
| |||
|