A powerful, feature-rich command-line interface for interacting with Model Context Provider servers.
A powerful, feature-rich command-line interface for interacting with Model Context Provider servers. This client enables seamless communication with LLMs through integration with the CHUK-MCP protocol library which is a pyodide compatible pure python protocol implementation of MCP, supporting tool usage, conversation management, and multiple operational modes.
The core protocol implementation has been moved to a separate package at: https://github.com/chrishayuk/chuk-mcp
This CLI is built on top of the protocol library, focusing on providing a rich user experience while the protocol library handles the communication layer.
Multiple Operational Modes:
Multi-Provider Support:
gpt-4o-mini, gpt-4o, gpt-4-turbo, etc.)llama3.2, qwen2.5-coder, etc.)Robust Tool System:
Advanced Conversation Management:
Rich User Experience:
Resilient Resource Management:
OPENAI_API_KEY environment variableserver_config.json)git clone https://github.com/chrishayuk/mcp-cli
cd mcp-cli
pip install -e ".[cli,dev]"
mcp-cli --help
If you prefer using UV for dependency management:
# Install UV if not already installed
pip install uv
# Install dependencies
uv sync --reinstall
# Run using UV
uv run mcp-cli --help
Global options available for all commands:
--server: Specify the server(s) to connect to (comma-separated for multiple)--config-file: Path to server configuration file (default: server_config.json)--provider: LLM provider to use (openai or ollama, default: openai)--model: Specific model to use (provider-dependent defaults)--disable-filesystem: Disable filesystem access (default: true)Chat mode provides a conversational interface with the LLM, automatically using available tools when needed:
mcp-cli chat --server sqlite
With specific provider and model:
mcp-cli chat --server sqlite --provider openai --model gpt-4o
mcp-cli chat --server sqlite --provider ollama --model llama3.2
In chat mode, use these slash commands:
/help: Show available commands/help <command>: Show detailed help for a specific command/quickhelp or /qh: Display a quick reference of common commandsexit or quit: Exit chat mode/tools: Display all available tools with their server information
/tools --all: Show detailed tool information including parameters/tools --raw: Show raw tool definitions/toolhistory or /th: Show history of tool calls in the current session
/th <N>: Show details for a specific tool call/th -n 5: Show only the last 5 tool calls/th --json: Show tool calls in JSON format/conversation or /ch: Show the conversation history
/ch <N>: Show a specific message from history/ch -n 5: Show only the last 5 messages/ch <N> --json: Show a specific message in JSON format/ch --json: View the entire conversation history in raw JSON format/save <filename>: Save conversation history to a JSON file/compact: Condense conversation history into a summary/cls: Clear the screen while keeping conversation history/clear: Clear both the screen and conversation history/verbose or /v: Toggle between verbose and compact tool display modes/interrupt, /stop, or /cancel: Interrupt running tool execution/provider <n>: Change the current LLM provider/model <n>: Change the current LLM model/servers: List connected servers and their statusInteractive mode provides a command-line interface with slash commands for direct server interaction:
mcp-cli interactive --server sqlite
In interactive mode, use these commands:
/ping: Check if server is responsive/prompts: List available prompts/tools: List available tools/tools-all: Show detailed tool information with parameters/tools-raw: Show raw tool definitions in JSON/resources: List available resources/chat: Enter chat mode/cls: Clear the screen/clear: Clear the screen and show welcome message/help: Show help message/exit or /quit: Exit the programCommand mode provides a Unix-friendly interface for automation and pipeline integration:
mcp-cli cmd --server sqlite [options]
This mode is designed for scripting, batch processing, and direct integration with other Unix tools.
--input: Input file path (use - for stdin)--output: Output file path (use - for stdout, default)--prompt: Prompt template (use {{input}} as placeholder for input)--raw: Output raw text without formatting--tool: Directly call a specific tool--tool-args: JSON arguments for tool call--system-prompt: Custom system promptProcess content with LLM:
# Summarize a document
mcp-cli cmd --server sqlite --input document.md --prompt "Summarize this: {{input}}" --output summary.md
# Process stdin and output to stdout
cat document.md | mcp-cli cmd --server sqlite --input - --prompt "Extract key points: {{input}}"
Call tools directly:
# List database tables
mcp-cli cmd --server sqlite --tool list_tables --raw
# Run a SQL query
mcp-cli cmd --server sqlite --tool read_query --tool-args '{"query": "SELECT COUNT(*) FROM users"}'
Batch processing:
# Process multiple files with GNU Parallel
ls *.md | parallel mcp-cli cmd --server sqlite --input {} --output {}.summary.md --prompt "Summarize: {{input}}"
Run individual commands without entering interactive mode:
# List available tools
mcp-cli tools list --server sqlite
# Call a specific tool
mcp-cli tools call --server sqlite
# List available prompts
mcp-cli prompts list --server sqlite
# Check server connectivity
mcp-cli ping --server sqlite
# List available resources
mcp-cli resources list --server sqlite
Create a server_config.json file with your server configurations:
{
"mcpServers": {
"sqlite": {
"command": "python",
"args": ["-m", "mcp_server.sqlite_server"],
"env": {
"DATABASE_PATH": "your_database.db"
}
},
"another-server": {
"command": "python",
"args": ["-m", "another_server_module"],
"env": {}
}
}
}
src/
├── mcp_cli/
│ ├── chat/ # Chat mode implementation
│ │ ├── commands/ # Chat slash commands
│ │ │ ├── __init__.py # Command registration system
│ │ │ ├── conversation.py # Conversation management
│ │ │ ├── conversation_history.py
│ │ │ ├── exit.py
│ │ │ ├── help.py
│ │ │ ├── help_text.py
│ │ │ ├── models.py
│ │ │ ├── servers.py
│ │ │ ├── tool_history.py
│ │ │ └── tools.py
│ │ ├── chat_context.py # Chat session state management
│ │ ├── chat_handler.py # Main chat loop handler
│ │ ├── command_completer.py # Command completion
│ │ ├── conversation.py # Conversation processor
│ │ ├── system_prompt.py # System prompt generator
│ │ ├── tool_processor.py # Tool handling
│ │ └── ui_manager.py # User interface
│ ├── commands/ # CLI commands
│ │ ├── __init__.py
│ │ ├── chat.py # Chat command
│ │ ├── cmd.py # Command mode
│ │ ├── interactive.py # Interactive mode
│ │ ├── ping.py # Ping command
│ │ ├── prompts.py # Prompts commands
│ │ ├── register_commands.py # Command registration
│ │ ├── resources.py # Resources commands
│ │ └── tools.py # Tools commands
│ ├── llm/ # LLM client implementations
│ │ ├── providers/ # Provider-specific clients
│ │ │ ├── __init__.py
│ │ │ ├── base.py # Base LLM client
│ │ │ └── openai_client.py # OpenAI implementation
│ │ ├── llm_client.py # Client factory
│ │ ├── system_prompt_generator.py # Prompt generator
│ │ └── tools_handler.py # Tools handling
│ ├── ui/ # User interface components
│ │ ├── colors.py # Color definitions
│ │ └── ui_helpers.py # UI utilities
│ ├── cli_options.py # CLI options processing
│ ├── config.py # Configuration loader
│ ├── main.py # Main entry point
│ └── run_command.py # Command execution
The MCP CLI can automatically execute tools provided by the server. In chat mode, simply request information that requires tool usage, and the LLM will automatically select and call the appropriate tools.
Example conversation:
You: What tables are available in the database?
Assistant: Let me check for you.
[Tool Call: list_tables]
I found the following tables in the database:
- users
- products
- orders
- categories
You: How many users do we have?
Assistant: I'll query the database for that information.
[Tool Call: read_query]
There are 873 users in the database.
Command mode enables powerful automation through shell scripts:
#!/bin/bash
# Example script to analyze multiple documents
# Process all markdown files in the current directory
for file in *.md; do
echo "Processing $file..."
# Generate summary
mcp-cli cmd --server sqlite --input "$file" \
--prompt "Summarize this document: {{input}}" \
--output "${file%.md}.summary.md"
# Extract entities
mcp-cli cmd --server sqlite --input "$file" \
--prompt "Extract all company names, people, and locations from this text: {{input}}" \
--output "${file%.md}.entities.txt" --raw
done
# Create a combined report
echo "Creating final report..."
cat *.entities.txt | mcp-cli cmd --server sqlite --input - \
--prompt "Analyze these entities and identify the most frequently mentioned:" \
--output report.md
Track and manage your conversation history:
> /conversation
Conversation History (12 messages)
# | Role | Content
1 | system | You are an intelligent assistant capable of using t...
2 | user | What tables are available in the database?
3 | assistant | Let me check for you.
4 | assistant | [Tool call: list_tables]
...
> /conversation 4
Message #4 (Role: assistant)
[Tool call: list_tables]
Tool Calls:
1. ID: call_list_tables_12345678, Type: function, Name: list_tables
Arguments: {}
> /save conversation.json
Conversation saved to conversation.json
> /compact
Conversation history compacted with summary.
Summary:
The user asked about database tables, and I listed the available tables (users, products, orders, categories). The user then asked about the number of users, and I queried the database to find there are 873 users.
The CLI is organized with optional dependency groups:
Install with specific extras using:
pip install "mcp-cli[cli]" # Basic CLI features
pip install "mcp-cli[cli,dev]" # CLI with development tools
Contributions are welcome! Please follow these steps:
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.