MCP SHELL (Model Context Protocol Shell)

A feature-rich command-line interface for interacting with Model Context Protocol (MCP) servers. Built for developers who want a powerful yet elegant way to explore and use MCP tools, resources, and prompts.

Key Features

• Multi-Transport Support: Connect via SSE, Stdio (Local), and Streamable HTTP.
• Daemon Mode: Background service for persistent connections and enhanced performance.
• Authentication: Secure OAuth2 flows with automatic token management.
• Discovery: Easily explore tools, resources, and prompt templates.
• Tool Execution: Call server tools directly from your terminal with type coercion and JSON support.
• Resource Access: Read resources in various formats.
• Flexible Configuration: Manage multiple servers in a single config.json file.

Installation

Ensure you have uv installed, then run:

uv sync

Usage

Configuration

The CLI looks for config.json in the current directory or ~/.mcp-shell/config.json.

{
  "mcpServers": {
    "your-server": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

List MCP Servers

See all configured servers and their health status in an interactive table.

mcp list [options]

Options:

• --json: Output results in JSON format.
• --verbose, -v: Show detailed configuration.
• --timeout <ms>: Connection timeout in milliseconds (default: 10000).

Deep Exploration

Explore server capabilities using a hierarchical tree view.

# Detailed view of everything (Tools, Resources, Prompts)
mcp list your-server

# Focused view of available tools
mcp tool your-server

# Inspect a specific tool's schema and documentation
mcp tool your-server.tool_name

# Explore resources
mcp resource your-server

# Explore prompts
mcp prompt your-server

Tool Execution

Call server tools directly from your terminal with automatic type coercion.

mcp tool your-server.tool_name key1=val1 key2=val2 [options]

Options:

• --json: Output result as JSON.
• --format <auto|json|raw>: Control output format.
• --timeout <ms>: Execution timeout in milliseconds.

Resources & Prompts

Interact with data sources and LLM templates.

# Read a specific resource
mcp resource your-server.resource_uri [options]

# Get a prompt template
mcp prompt your-server.prompt_name [options]

Options:

• --json: Output as JSON.
• --timeout <ms>: Request timeout.

Daemon Management

Manage the background service for persistent, high-performance connections.

mcp daemon start
mcp daemon status
mcp daemon stop

Authentication

Securely authorize servers using browser-based OAuth2 flows. The CLI automates token resets if expired credentials are detected.

mcp auth your-server [--timeout <ms>]

License

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

Collaboration

We welcome collaboration! Please see our Contributing Guide for details on how to get started, report bugs, or submit pull requests.