mcp-execution-cli

Command-line interface for MCP Code Execution progressive loading. Achieves 98% token savings by generating one TypeScript file per MCP tool.

Installation

Pre-built binaries

Download from GitHub Releases:

# macOS (Apple Silicon)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-macos-arm64.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-macos-amd64.tar.gz | tar xz

# Linux (x86_64)
curl -L https://github.com/bug-ops/mcp-execution/releases/latest/download/mcp-execution-cli-linux-amd64.tar.gz | tar xz

From crates.io

cargo install mcp-execution-cli

From source

git clone https://github.com/bug-ops/mcp-execution
cd mcp-execution
cargo install --path crates/mcp-cli

[!IMPORTANT] Requires Rust 1.89 or later for building from source.

Usage

Generate Progressive Loading Files

# From config file (recommended)
mcp-execution-cli generate --from-config github

# With manual configuration
mcp-execution-cli generate github-mcp-execution-server --env GITHUB_TOKEN=ghp_xxx

[!TIP] Use --from-config to load server configuration from ~/.claude/mcp.json.

Discover Available Tools

# List available servers
ls ~/.claude/servers/

# List tools in a server
ls ~/.claude/servers/github/

# Load one tool (98% token savings!)
cat ~/.claude/servers/github/createIssue.ts

Shell Completions

# Bash
mcp-execution-cli completions bash > /etc/bash_completion.d/mcp-execution-cli

# Zsh
mcp-execution-cli completions zsh > ~/.zsh/completions/_mcp-execution-cli

# Fish
mcp-execution-cli completions fish > ~/.config/fish/completions/mcp-execution-cli.fish

Commands

generate

Generate TypeScript files with progressive loading:

mcp-execution-cli generate <SERVER> [OPTIONS]

Options:

• --from-config <NAME>: Load config from mcp.json
• --arg <ARG>: Server command argument (repeatable)
• --env <KEY=VALUE>: Environment variable (repeatable)
• --progressive-output <PATH>: Custom output directory
• --format <FORMAT>: Output format (json, text, pretty)

Examples:

# From config
mcp-execution-cli generate --from-config github

# Docker container
mcp-execution-cli generate docker \
  --arg=run --arg=-i --arg=--rm \
  --arg=ghcr.io/org/server \
  --env=API_KEY=xxx

introspect

Analyze MCP servers and discover capabilities:

mcp-execution-cli introspect <SERVER> [OPTIONS]

Configuration Modes:

1. Load from ~/.claude/mcp.json (recommended):

   mcp-execution-cli introspect --from-config github
   

2. Manual configuration:

   mcp-execution-cli introspect github-mcp-execution-server --arg=stdio
   

Options:

• --from-config <NAME>: Load config from mcp.json
• --arg <ARG>: Server command argument (repeatable)
• --env <KEY=VALUE>: Environment variable (repeatable)
• --detailed: Show full input/output schemas
• --format <FORMAT>: Output format (json, text, pretty)
• --http <URL>: Use HTTP transport
• --sse <URL>: Use SSE transport

Examples:

# From config with detailed schemas
mcp-execution-cli introspect --from-config github --detailed

# Manual with Docker
mcp-execution-cli introspect docker \
  --arg=run --arg=-i --arg=--rm \
  --arg=ghcr.io/github/github-mcp-execution-server \
  --env=GITHUB_TOKEN=ghp_xxx

# HTTP transport
mcp-execution-cli introspect --http https://api.example.com/mcp \
  --header "Authorization=Bearer token"

skill

Generate Claude Code skill files (SKILL.md) from progressive loading tools:

mcp-execution-cli skill --server <SERVER_ID> [OPTIONS]

Options:

• --server, -s <ID>: Server identifier (required)
• --servers-dir <PATH>: Custom servers directory
• --output, -o <PATH>: Custom output path
• --skill-name <NAME>: Custom skill name
• --hint <HINT>: Use case hints (repeatable)
• --overwrite: Overwrite existing SKILL.md

Examples:

# Generate skill for GitHub server
mcp-execution-cli skill --server github

# With custom output and hints
mcp-execution-cli skill --server github \
  --output ~/.claude/skills/github/SKILL.md \
  --hint "managing pull requests" \
  --hint "code review"

# Overwrite existing skill
mcp-execution-cli skill --server github --overwrite

[!TIP] For optimal results, prefer using the MCP server (mcp-execution-server) for skill generation. The MCP server can leverage LLM capabilities to summarize tool descriptions and reduce context size, resulting in more concise and effective skill files.

stats

View cache statistics:

mcp-execution-cli stats

completions

Generate shell completions:

mcp-execution-cli completions <SHELL>

[!NOTE] Supported shells: bash, zsh, fish, powershell

Features

• Progressive Loading: One TypeScript file per MCP tool
• Type-Safe: Full TypeScript interfaces from MCP schemas
• Multiple Transports: stdio, HTTP, SSE, Docker
• Shell Completions: bash, zsh, fish, PowerShell
• Fast: ~2-3ms generation time per server

Token Savings

Security

• No Code Execution: Generated TypeScript is for type information only
• Command Injection Prevention: All user input validated
• Path Validation: Rejects malicious paths
• Template Security: Handlebars escapes all user input

[!WARNING] Never pass untrusted input directly to --arg or --env options.

Related Crates

This crate is part of the mcp-execution workspace:

• mcp-execution-core - Foundation types
• mcp-execution-introspector - MCP server analysis
• mcp-execution-codegen - TypeScript code generation
• mcp-execution-files - Virtual filesystem
• mcp-execution-skill - Skill generation
• mcp-execution-server - MCP server

MSRV Policy

Minimum Supported Rust Version: 1.89

MSRV increases are considered minor version bumps.

License

Licensed under either of Apache License 2.0 or MIT license at your option.