Back to MCP Servers

Cli

Yet another CLI tool for testing MCP servers

other-tools-and-integrationstesting
By chrishayuk
2.0k301Updated 2 weeks agoPythonApache-2.0

Installation

npx -y mcp-cli

Configuration

{
  "mcpServers": {
    "mcp-cli": {
      "command": "npx",
      "args": ["-y", "mcp-cli"]
    }
  }
}

How to use

  1. Run the installation command above (if needed)
  2. Open your Claude Code settings file (~/.claude/settings.json)
  3. Add the configuration to the mcpServers section
  4. Restart Claude Code to apply changes

README

View on GitHub

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

…

View source on GitHub

You might also like

Ai Vision
MCP Servers
Cli
MCP Servers
Playwright Browser Automation
MCP Servers