Labsco
chrishayuk logo

MCP CLI

★ 2,000

from chrishayuk

A command-line interface for interacting with Model Context Protocol servers.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#social-media#notion#calendar#scraping#browser#database#cloud

MCP CLI - Model Context Protocol Command Line Interface

CI PyPI version

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.

🆕 Recent Updates (v0.16)

AI Virtual Memory (Experimental)

  • --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)
  • Multimodal page_fault: Image pages return multi-block content (text + image_url) so multimodal models can re-analyze recalled images
  • /memory page <id> --download: Export page content to local files with modality-aware extensions (.txt, .json, .png)

Execution Plans (Tier 6)

  • /plan command: Create, inspect, and execute reproducible tool call graphs — create, list, show, run, delete, resume
  • Model-driven planning (--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 terminal
  • Parallel batch execution: Independent plan steps run concurrently via topological batching (Kahn's BFS), with configurable max_concurrency
  • Variable resolution: ${var}, ${var.field} nested access, and template strings like "https://${api.host}/users" — type-preserving for single refs
  • Dry-run mode: Trace planned tool calls without executing — safe for production inspection
  • Checkpointing & resume: Execution state persisted after each batch; resume interrupted plans with /plan resume <id>
  • Guard integration: Plans respect existing budget, per-tool limits, and runaway detection guards
  • DAG visualization: ASCII rendering with status indicators (○/◉/●/✗) and parallel markers (∥)
  • Re-planning: Optional LLM-based re-planning on step failure (enable_replan=True)
  • Powered by: chuk-ai-planner graph-based plan DSL

MCP Apps (SEP-1865)

  • Interactive HTML UIs: MCP servers can serve interactive HTML applications (charts, tables, maps, markdown viewers) that render in your browser
  • Sandboxed iframes: Apps run in secure sandboxed iframes with CSP protection
  • WebSocket bridge: Real-time bidirectional communication between browser apps and MCP servers
  • Automatic launch: Tools with _meta.ui annotations automatically open in the browser when called
  • Session reliability: Message queuing, reconnection with exponential backoff, deferred tool result delivery

Production Hardening

  • Secret Redaction: All log output (console and file) is automatically redacted for Bearer tokens, API keys, OAuth tokens, and Authorization headers
  • Structured File Logging: Optional --log-file flag enables rotating JSON log files (10MB, 3 backups) at DEBUG level
  • Per-Server Timeouts: Server configs support tool_timeout and init_timeout overrides, resolved per-server → global → default
  • Thread-Safe OAuth: Concurrent OAuth flows serialized with asyncio.Lock and copy-on-write header mutation
  • Server Health Monitoring: /health command, health-check-on-failure diagnostics, optional --health-interval background polling

Performance & Polish

  • O(1) Tool Lookups: Indexed tool lookup replacing O(n) linear scans
  • Cached LLM Tool Metadata: Per-provider caching with automatic invalidation
  • Startup Progress: Real-time progress messages during initialization
  • Token Usage Tracking: Per-turn and cumulative tracking with /usage command (aliases: /tokens, /cost)
  • Session Persistence: Save/load/list conversation sessions with auto-save every 10 turns (/sessions)
  • Conversation Export: Export conversations as Markdown or JSON with metadata (/export)

Dashboard (Real-Time Browser UI)

  • --dashboard flag: Launch a real-time browser dashboard alongside chat mode
  • Agent Terminal: Live conversation view with message bubbles, streaming tokens, and attachment rendering
  • Activity Stream: Tool call/result pairs, reasoning steps, and user attachment events
  • Plan Viewer: Visual execution plan progress with DAG rendering
  • Tool Registry: Browse discovered tools, trigger execution from the browser
  • Config Panel: View and switch providers, models, and system prompt
  • File Attachments: "+" button for browser file upload, drag-and-drop, and clipboard paste

Multi-Modal Attachments

  • /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)
  • Inline @file: references: Mention @file:path/to/file anywhere in a message to attach it
  • Image URL detection: HTTP/HTTPS image URLs in messages are automatically sent as vision content
  • Supported formats: PNG, JPEG, GIF, WebP, HEIC (images), MP3, WAV (audio), plus 25+ text/code extensions
  • Dashboard rendering: Image thumbnails, expandable text previews, audio players, file badges
  • Browser upload: "+" button in dashboard chat input with drag-and-drop and clipboard paste support

Code Quality

  • Core/UI Separation: Core modules use logging only — no UI imports
  • 4,300+ tests: Comprehensive test suite with branch coverage, integration tests, and 60% minimum threshold
  • 15 Architecture Principles: Documented and enforced (see architecture.md)
  • Full Roadmap: Tiers 1-6 complete, Tiers 7-12 planned (traces, memory scopes, skills, scheduling, multi-agent)

🔄 Architecture Overview

The MCP CLI is built on a modular architecture with clean separation of concerns:

  • CHUK Tool Processor: Production-grade async tool execution with middleware (retry, circuit breaker, rate limiting), multiple execution strategies, and observability
  • CHUK-LLM: Unified LLM provider with dynamic model discovery, capability-based selection, and llama.cpp integration (1.53x faster than Ollama with automatic model reuse)
  • CHUK-Term: Enhanced terminal UI with themes, cross-platform terminal management, and rich formatting
  • MCP CLI: Command orchestration and integration layer (this project)

🌟 Features

Multiple Operational Modes

  • Chat Mode: Conversational interface with streaming responses and automated tool usage (default: Ollama/gpt-oss)
  • Interactive Mode: Command-driven shell interface for direct server operations
  • Command Mode: Unix-friendly mode for scriptable automation and pipelines
  • Direct Commands: Run individual commands without entering interactive mode

Advanced Chat Interface

  • Streaming Responses: Real-time response generation with live UI updates
  • Reasoning Visibility: See AI's thinking process with reasoning models (gpt-oss, GPT-5, Claude 4.5)
  • Concurrent Tool Execution: Execute multiple tools simultaneously while preserving conversation order
  • Smart Interruption: Interrupt streaming responses or tool execution with Ctrl+C
  • Performance Metrics: Response timing, words/second, and execution statistics
  • Rich Formatting: Markdown rendering, syntax highlighting, and progress indicators
  • Token Usage Tracking: Per-turn and cumulative API token usage with /usage command
  • Multi-Modal Attachments: Attach images, text files, and audio to messages via /attach, --attach, @file: refs, or browser upload
  • Session Persistence: Auto-save and manual save/load of conversation sessions
  • Conversation Export: Export to Markdown or JSON with metadata and token usage

Comprehensive Provider Support

MCP CLI supports all providers and models from CHUK-LLM, including cutting-edge reasoning models:

ProviderKey ModelsSpecial Features
Ollama (Default)🧠 gpt-oss, llama3.3, llama3.2, qwen3, qwen2.5-coder, deepseek-coder, granite3.3, mistral, gemma3, phi3, codellamaLocal 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 SonnetEnhanced reasoning, long context
Azure OpenAI 🏢Enterprise GPT-5, GPT-4 modelsPrivate endpoints, compliance, audit logs
Google GeminiGemini 2.0 Flash, Gemini 1.5 ProMultimodal, fast inference
Groq ⚡Llama 3.1 models, MixtralUltra-fast inference (500+ tokens/sec)
Perplexity 🌐Sonar modelsReal-time web search with citations
IBM watsonx 🏢Granite, Llama modelsEnterprise compliance
Mistral AI 🇪🇺Mistral Large, MediumEuropean, efficient models

Robust Tool System (Powered by CHUK Tool Processor v0.22+)

  • Automatic Discovery: Server-provided tools are automatically detected and catalogued
  • Provider Adaptation: Tool names are automatically sanitized for provider compatibility
  • Production-Grade Execution: Middleware layers with timeouts, retries, exponential backoff, caching, and circuit breakers
  • Multiple Execution Strategies: In-process (fast), isolated subprocess (safe), or remote via MCP
  • Concurrent Execution: Multiple tools can run simultaneously with proper coordination
  • Rich Progress Display: Real-time progress indicators and execution timing
  • Tool History: Complete audit trail of all tool executions
  • Middleware: Retry with exponential backoff, circuit breakers, and rate limiting via CTP
  • Streaming Tool Calls: Support for tools that return streaming data

MCP Apps (Interactive UIs)

  • Browser-based UIs: MCP servers can serve interactive HTML applications that render in your browser
  • Automatic Detection: Tools with _meta.ui annotations automatically launch browser apps on tool call
  • Sandboxed Execution: Apps run in secure sandboxed iframes with Content Security Policy protection
  • WebSocket Bridge: Real-time JSON-RPC bridge between browser apps and MCP tool servers
  • Session Persistence: Message queuing during disconnects, automatic reconnection, deferred tool result delivery
  • structuredContent Support: Full MCP spec compliance including structured content extraction and forwarding

Execution Plans (Powered by chuk-ai-planner)

  • Plan Creation: Generate execution plans from natural language descriptions using LLM-based plan agents
  • Model-Driven Planning: With --plan-tools, the LLM autonomously decides when to plan — calls plan_create_and_execute for complex multi-step tasks, uses regular tools for simple ones
  • DAG Execution: Plans are directed acyclic graphs — independent steps run in parallel batches, dependent steps wait
  • Variable Resolution: Step outputs bind to variables (result_variable), referenced by later steps as ${var} or ${var.field}
  • Dry-Run Mode: Trace what a plan would do without executing any tools — safe for production
  • Checkpointing: Execution state saved after each batch; resume interrupted plans without re-running completed steps
  • Guard Integration: Plans share budget and per-tool limits with the conversation — no bypass
  • Re-planning: On step failure, optionally invoke the LLM to generate a revised plan for remaining work
  • DAG Visualization: ASCII rendering shows dependency structure, batch grouping, and parallel markers
  • Persistence: Plans stored as JSON at ~/.mcp-cli/plans/

Advanced Configuration Management

  • Environment Integration: API keys and settings via environment variables
  • File-based Config: YAML and JSON configuration files
  • User Preferences: Persistent settings for active providers and models
  • Validation & Diagnostics: Built-in provider health checks and configuration validation

Enhanced User Experience

  • Cross-Platform Support: Windows, macOS, and Linux with platform-specific optimizations via chuk-term
  • Rich Console Output: Powered by chuk-term with 8 built-in themes (default, dark, light, minimal, terminal, monokai, dracula, solarized)
  • Advanced Terminal Management: Cross-platform terminal operations including clearing, resizing, color detection, and cursor control
  • Interactive UI Components: User input handling through chuk-term's prompt system (ask, confirm, select_from_list, select_multiple)
  • Command Completion: Context-aware tab completion for all interfaces
  • Comprehensive Help: Detailed help system with examples and usage patterns
  • Graceful Error Handling: User-friendly error messages with troubleshooting hints

📚 Documentation

Comprehensive documentation is available in the docs/ directory:

Project

  • Architecture - 15 design principles, module layout, and coding conventions
  • Roadmap - Vision, completed tiers (1-5), and planned tiers (6-12: plans, traces, skills, scheduling, multi-agent, remote sessions)

Core Documentation

  • Commands System - Complete guide to the unified command system, patterns, and usage across all modes
  • Token Management - Comprehensive token management for providers and servers including OAuth, bearer tokens, and API keys

Specialized Documentation

  • Execution Plans - Plan creation, parallel execution, variable resolution, checkpointing, guards, and re-planning
  • Dashboard - Real-time browser UI with agent terminal, activity stream, and file uploads
  • Attachments - Multi-modal file attachments: images, text, audio, and browser upload
  • MCP Apps - Interactive browser UIs served by MCP servers (SEP-1865)
  • OAuth Authentication - OAuth flows, storage backends, and MCP server integration
  • Streaming Integration - Real-time response streaming architecture
  • Package Management - Dependency organization and feature groups

UI Documentation

Testing Documentation

🌐 Available Modes

1. Chat Mode (Default)

Provides a natural language interface with streaming responses and automatic tool usage:

Copy & paste — that's it
# 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

2. Interactive Mode

Command-driven shell interface for direct server operations:

Copy & paste — that's it
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

3. Command Mode

Unix-friendly interface for automation and scripting:

Copy & paste — that's it
# 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 -

4. Direct Commands

Execute individual commands without entering interactive mode:

Copy & paste — that's it
# 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 (Interactive Browser UIs)

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.

Prerequisites

Copy & paste — that's it
# Install the apps extra (adds websockets dependency)
pip install "mcp-cli[apps]"

How It Works

  1. Connect to an MCP server that provides app-enabled tools
  2. Call a tool that has _meta.ui metadata (e.g., show_chart, show_table)
  3. mcp-cli automatically fetches the UI resource, starts a local server, and opens your browser
  4. The app receives tool results in real-time via WebSocket

Example

Copy & paste — that's it
# 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

Architecture

  • Host page serves a sandboxed iframe with the app HTML
  • WebSocket bridge proxies JSON-RPC between the browser and MCP servers
  • Security: Iframe sandbox, CSP protection, XSS prevention, URL scheme validation
  • Reliability: Message queuing during disconnects, exponential backoff reconnection, deferred tool result delivery

See MCP Apps Documentation for the full guide.

🤖 Using Chat Mode

Chat mode provides the most advanced interface with streaming responses and intelligent tool usage.

Starting Chat Mode

Copy & paste — that's it
# 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

Chat Commands (Slash Commands)

Provider & Model Management

Copy & paste — that's it
/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

Tool Management

Copy & paste — that's it
/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 Management (Runtime Configuration)

Copy & paste — that's it
/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.

Multi-Modal Attachments

Copy & paste — that's it
/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 Management

Copy & paste — that's it
/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

UI Customization

Copy & paste — that's it
/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 Management

Copy & paste — that's it
/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:

  • Keychain (macOS) - Uses macOS Keychain (default on macOS)
  • Windows Credential Manager - Native Windows storage (default on Windows)
  • Secret Service - Linux desktop keyring (GNOME/KDE)
  • Encrypted File - AES-256 encrypted local files (cross-platform fallback)
  • HashiCorp Vault - Enterprise secret management

Override the default backend with --token-backend:

Copy & paste — that's it
# 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.

Session Control

Copy & paste — that's it
/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                            # Show all commands
/help tools                       # Help for specific command
/exit                            # Exit chat mode

For complete command documentation, see Commands System Guide.

Chat Features

Streaming Responses with Reasoning Visibility

  • 🧠 Reasoning Models: See the AI's thinking process with gpt-oss, GPT-5, Claude 4
  • Real-time Generation: Watch text appear token by token
  • Performance Metrics: Words/second, response time
  • Graceful Interruption: Ctrl+C to stop streaming
  • Progressive Rendering: Markdown formatted as it streams

Tool Execution

  • Automatic tool discovery and usage
  • Concurrent execution with progress indicators
  • Verbose and compact display modes
  • Complete execution history and timing

Multi-Modal Attachments

  • Attach images, text files, and audio to any message
  • /attach command with staging, list, and clear (aliases: /file, /image)
  • Inline @file:path references in any message
  • --attach CLI flag for first-message attachments
  • Browser "+" button with drag-and-drop and clipboard paste (with --dashboard)
  • Dashboard renders thumbnails, text previews, and audio players

Provider Integration

  • Seamless switching between providers
  • Model-specific optimizations
  • API key and endpoint management
  • Health monitoring and diagnostics

🖥️ Using Interactive Mode

Interactive mode provides a command shell for direct server interaction.

Starting Interactive Mode

Copy & paste — that's it
mcp-cli interactive --server sqlite

Interactive Commands

Copy & paste — that's it
help                              # Show available commands
exit                              # Exit interactive mode
clear                             # Clear terminal

# Provider management
provider                          # Show current provider
provider list                     # List providers
provider anthropic                # Switch provider
provider openai gpt-5             # Switch to GPT-5

# Model management
model                             # Show current model
model gpt-oss                     # Switch to reasoning model
model claude-4-5-opus             # Switch to Claude 4.5
models                            # List available models

# Tool operations
tools                             # List tools
tools --all                       # Detailed tool info
tools call                        # Interactive tool execution

# Server operations
servers                           # List servers
ping                              # Ping all servers
resources                         # List resources
prompts                           # List prompts

📄 Using Command Mode

Command mode provides Unix-friendly automation capabilities.

Command Mode Options

Copy & paste — that's it
--input FILE                      # Input file (- for stdin)
--output FILE                     # Output file (- for stdout)
--prompt TEXT                     # Prompt template
--tool TOOL                       # Execute specific tool
--tool-args JSON                  # Tool arguments as JSON
--system-prompt TEXT              # Custom system prompt
--raw                             # Raw output without formatting
--single-turn                     # Disable multi-turn conversation
--max-turns N                     # Maximum conversation turns

Examples

Copy & paste — that's it
# Text processing with reasoning models
echo "Analyze this data" | mcp-cli cmd --server sqlite --model gpt-oss --input - --output analysis.txt

# Use GPT-5 for complex analysis
mcp-cli cmd --server sqlite --provider openai --model gpt-5 --prompt "Provide strategic analysis" --input report.txt

# Tool execution
mcp-cli cmd --server sqlite --tool list_tables --raw

# Complex queries
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'

# Batch processing with GNU Parallel
ls *.txt | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary --prompt "Summarize: {{input}}"

🔒 Security Considerations

Privacy & Local-First

  • Local by Default: Ollama with gpt-oss runs locally, keeping your data private
  • No Cloud Required: Full functionality without external API dependencies

Token & Authentication Security

  • Secure Token Storage: Tokens stored in OS-native credential stores (macOS Keychain, Windows Credential Manager, Linux Secret Service) under the "mcp-cli" service identifier
  • Multiple Storage Backends: Choose between keychain, encrypted files, or HashiCorp Vault based on security requirements
  • API Keys: Only needed for cloud providers (OpenAI, Anthropic, etc.), stored securely using token management system
  • OAuth 2.0 Support: Secure authentication for MCP servers using PKCE and resource indicators (RFC 7636, RFC 8707)

Log Security

  • Secret Redaction: All log output (console and file) is automatically redacted for Bearer tokens, API keys (sk-*), OAuth access tokens, and Authorization headers
  • Rotating File Logs: Optional --log-file with JSON format, 10MB rotation, and 3 backup files

Execution Security

  • Tool Validation: All tool calls are validated before execution
  • Timeout Protection: Configurable timeouts prevent hanging operations (v0.13+)
  • Circuit Breakers: Automatic failure detection and recovery to prevent cascading failures (v0.13+)
  • Server Isolation: Each server runs in its own process
  • File Access: Filesystem access can be disabled with --disable-filesystem
  • Transport Monitoring: Automatic detection of connection failures with warnings (v0.11+)

MCP Apps Security

  • Iframe Sandbox: Apps run in sandboxed iframes with restricted permissions
  • Content Security Policy: Server-supplied CSP domains are validated and sanitized
  • XSS Prevention: Tool names and user-supplied content are HTML-escaped before template injection
  • URL Scheme Validation: ui/open-link only allows http:// and https:// schemes
  • Tool Name Validation: Bridge rejects tool names not matching the MCP spec character set

🚀 Performance Features

LLM Provider Performance (v0.16+)

  • 52x Faster Imports: Reduced from 735ms to 14ms through lazy loading
  • 112x Faster Client Creation: Automatic thread-safe caching
  • llama.cpp Integration: 1.53x faster inference (311 vs 204 tokens/sec) with automatic Ollama model reuse
  • Dynamic Model Discovery: Zero overhead capability-based model selection

Tool Execution Performance (v0.13+)

  • Production Middleware: Timeouts, retries with exponential backoff, circuit breakers, and result caching
  • Concurrent Tool Execution: Multiple tools can run simultaneously with proper coordination
  • Connection Health Monitoring: Automatic detection and recovery from transport failures
  • Optimized Tool Manager: Reduced from 2000+ to ~800 lines while maintaining all functionality

Runtime Performance

  • Local Processing: Default Ollama provider minimizes latency
  • Reasoning Visibility: See AI thinking process with gpt-oss, GPT-5, Claude 4
  • Streaming Responses: Real-time response generation
  • Connection Pooling: Efficient reuse of client connections
  • Caching: Tool metadata and provider configurations are cached
  • Async Architecture: Non-blocking operations throughout

📦 Dependencies

Core dependencies are organized into feature groups:

  • cli: Terminal UI and command framework (Rich, Typer, chuk-term)
  • dev: Development tools, testing utilities, linting
  • chuk-tool-processor v0.22+: Production-grade tool execution with middleware, multiple execution strategies, and observability
  • chuk-llm v0.17+: Unified LLM provider with dynamic model discovery, capability-based selection, and llama.cpp integration
  • chuk-term: Enhanced terminal UI with themes, prompts, and cross-platform support

Install with specific features:

Copy & paste — that's it
pip install "mcp-cli[cli]"        # Basic CLI features
pip install "mcp-cli[cli,dev]"    # CLI with development tools
pip install "mcp-cli[apps]"       # MCP Apps (interactive browser UIs)

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

Copy & paste — that's it
git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e ".[cli,dev]"
pre-commit install

Demo Scripts

Explore the capabilities of MCP CLI:

Copy & paste — that's it
# Command Mode Demos

# General cmd mode features (bash)
bash examples/cmd_mode_demo.sh

# LLM integration with cmd mode (bash)
bash examples/cmd_mode_llm_demo.sh

# Python integration example
uv run examples/cmd_mode_python_demo.py

# Custom Provider Management Demos

# Interactive walkthrough demo (educational)
uv run examples/custom_provider_demo.py

# Working demo with actual inference (requires OPENAI_API_KEY)
uv run examples/custom_provider_working_demo.py

# Simple shell script demo (requires OPENAI_API_KEY)
bash examples/custom_provider_simple_demo.sh

# Terminal management features (chuk-term)
uv run examples/ui_terminal_demo.py

# Output system with themes (chuk-term)
uv run examples/ui_output_demo.py

# Streaming UI capabilities (chuk-term)
uv run examples/ui_streaming_demo.py

Running Tests

Copy & paste — that's it
pytest
pytest --cov=mcp_cli --cov-report=html

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

  • CHUK Tool Processor - Production-grade async tool execution with middleware and observability
  • CHUK-LLM - Unified LLM provider with dynamic model discovery, llama.cpp integration, and GPT-5/Claude 4.5 support (v0.17+)
  • CHUK-Term - Enhanced terminal UI with themes and cross-platform support
  • Rich - Beautiful terminal formatting
  • Typer - CLI framework
  • Prompt Toolkit - Interactive input

🔗 Related Projects

  • Model Context Protocol - Core protocol specification
  • MCP Servers - Official MCP server implementations
  • CHUK Tool Processor - Production-grade tool execution with middleware and observability
  • CHUK-LLM - LLM provider abstraction with dynamic model discovery, GPT-5, Claude 4.5, O3 series support, and llama.cpp integration
  • CHUK-Term - Terminal UI library with themes and cross-platform support