TurboMCP CLI

CLI for MCP servers with complete protocol support

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Usage
• Commands
• Transport Support
• Examples
• Related Tools

Overview

turbomcp-cli is a command-line interface for the Model Context Protocol, built on the turbomcp-client library. It provides complete MCP protocol coverage with rich, multi-format output and smart transport auto-detection.

Features

• 🎯 Complete MCP Protocol - All operations: tools, resources, prompts, completions, sampling, logging
• 🔧 Tool Management - List, call, and export tool schemas
• 📦 Resource Access - List, read, and subscribe to MCP resources
• 💬 Prompt Operations - List and execute prompts with arguments
• 🌐 Multi-Transport - STDIO (child process), TCP, Unix sockets, HTTP SSE, WebSocket
• 🚀 Smart Auto-Detection - Automatically detects transport from URL format
• 🎨 Rich Output - Human, JSON, YAML, and table formats with colored output
• 🛡️ Built on Core Libraries - Uses turbomcp-client and turbomcp-transport
• ⚡ Error Handling - Comprehensive error handling with actionable suggestions

Installation

From Crates.io

# Install latest stable version
cargo install turbomcp-cli

# Install specific version
cargo install turbomcp-cli --version 2.2.2

From Source

git clone https://github.com/Epistates/turbomcp.git
cd turbomcp
cargo install --path crates/turbomcp-cli

Quick Start

# List tools from a server
turbomcp-cli tools list --command "./my-mcp-server"

# Call a tool with arguments
turbomcp-cli tools call calculate --arguments '{"a": 5, "b": 3}'

# Get server information
turbomcp-cli server info

# List resources
turbomcp-cli resources list --url tcp://localhost:8080

# Work with prompts
turbomcp-cli prompts list --url unix:///tmp/mcp.sock

Usage

turbomcp-cli <COMMAND>

Commands:
  tools       Tool operations (list, call, schema, export)
  resources   Resource operations (list, read, templates, subscribe)
  prompts     Prompt operations (list, get, schema)
  complete    Completion operations
  server      Server management (info, ping, log-level, roots)
  sample      Sampling operations (advanced)
  connect     Interactive connection wizard
  status      Connection status
  help        Print help information

Global Options:
  -f, --format <FORMAT>     Output format [default: human] [possible: human, json, yaml, table, compact]
  -v, --verbose             Enable verbose output
  -c, --connection <NAME>   Use saved connection from config
  --no-color                Disable colored output
  -h, --help                Print help
  -V, --version             Print version

Connection Options

All commands support these connection options:

• --url <URL> - Server URL for HTTP/WebSocket or command path for STDIO (default: http://localhost:8080/mcp)
• --command <COMMAND> - Command to execute for STDIO transport (overrides --url)
• --auth <AUTH> - Bearer token or API key for authentication
• --json - Output results in JSON format

Commands

tools list - List Available Tools

List all tools available from an MCP server.

# List tools from HTTP server
turbomcp-cli tools list --url http://localhost:8080/mcp

# List tools from WebSocket server
turbomcp-cli tools list --url ws://localhost:8080/mcp

# List tools from STDIO server
turbomcp-cli tools list --command "./target/debug/my-server"

Example Output:

Available Tools:
- calculator_add: Add two numbers together
- file_read: Read contents of a file
- search_web: Search the web for information

Total: 3 tools

tools call - Call a Tool

Execute a specific tool on the MCP server.

# Call a tool with JSON parameters (HTTP)
turbomcp-cli tools call calculator_add \
    --url http://localhost:8080/mcp \
    --arguments '{"a": 5, "b": 3}'

# Call a tool via WebSocket
turbomcp-cli tools call file_read \
    --url ws://localhost:8080/mcp \
    --arguments '{"path": "/etc/hosts"}'

# Call a tool via STDIO
turbomcp-cli tools call calculator_add \
    --command "./target/debug/my-server" \
    --arguments '{"a": 5, "b": 3}'

Example Output:

{
  "result": 8,
  "success": true
}

tools schema - Export Tool Schemas

Export JSON schemas for all tools from an MCP server.

# Export schemas to stdout (HTTP)
turbomcp-cli tools schema --url http://localhost:8080/mcp

# Export schemas to file (HTTP)
turbomcp-cli tools schema \
    --url http://localhost:8080/mcp \
    --output schemas.json

# Export schemas from STDIO server
turbomcp-cli tools schema \
    --command "./target/debug/my-server" \
    --output schemas.json

Example Output:

{
  "tools": [
    {
      "name": "calculator_add",
      "description": "Add two numbers together",
      "inputSchema": {
        "type": "object",
        "properties": {
          "a": {"type": "number"},
          "b": {"type": "number"}
        },
        "required": ["a", "b"]
      }
    }
  ]
}

Transport Support

The CLI supports three transport methods:

HTTP/HTTPS

turbomcp-cli tools list --url http://localhost:8080/mcp
turbomcp-cli tools list --url https://api.example.com/mcp

WebSocket

turbomcp-cli tools list --url ws://localhost:8080/mcp
turbomcp-cli tools list --url wss://api.example.com/mcp

STDIO (Standard Input/Output)

# Using --command option
turbomcp-cli tools list --command "./my-server"
turbomcp-cli tools list --command "python server.py"

# Or specify path in --url (auto-detected)
turbomcp-cli tools list --url "./my-server"

Transport Auto-Detection:

• URLs starting with http://, https:// → HTTP transport
• URLs starting with ws://, wss:// → WebSocket transport
• --command option or executable paths → STDIO transport

Examples

# List tools from HTTP server
turbomcp-cli tools list --url http://localhost:8080/mcp

# Call calculator tool via STDIO
turbomcp-cli tools call calculator_add \
  --command "./target/debug/calculator-server" \
  --arguments '{"a": 10, "b": 5}'

# Export all schemas to file via WebSocket
turbomcp-cli tools schema \
  --url ws://localhost:8080/mcp \
  --output my-server-schemas.json

# Test STDIO server with authentication
turbomcp-cli tools list \
  --command "python my-server.py" \
  --auth "bearer-token-here" \
  --json

Roadmap

Planned: Secure Credential Storage

Status: Not yet implemented

Modern CLI best practices mandate using OS-native credential stores for storing long-lived tokens:

Planned commands:

# Future: Secure login flow
turbomcp-cli auth login --provider github
turbomcp-cli auth login --url https://mcp.example.com

# Future: Use stored credentials automatically
turbomcp-cli tools list --url https://mcp.example.com  # Uses keychain

# Future: Logout / clear credentials
turbomcp-cli auth logout --url https://mcp.example.com

Current workaround: Pass tokens via --auth flag or environment variables:

export MCP_AUTH_TOKEN="your-token"
turbomcp-cli tools list --url https://mcp.example.com --auth "$MCP_AUTH_TOKEN"

This feature will be implemented using the keyring crate for cross-platform credential storage.

Related Tools

• turbomcp - Main TurboMCP framework
• turbomcp-server - Server implementation
• turbomcp-client - Client implementation
• turbomcp-transport - Transport protocols

License

Licensed under the MIT License.

Part of the TurboMCP Rust SDK for the Model Context Protocol.