@aurracloud/mcp-cli NPM

MCP CLI

███╗   ███╗ ██████╗██████╗ 
████╗ ████║██╔════╝██╔══██╗
██╔████╔██║██║     ██████╔╝
██║╚██╔╝██║██║     ██╔═══╝ 
██║ ╚═╝ ██║╚██████╗██║     
╚═╝     ╚═╝ ╚═════╝╚═╝     
By aurracloud.com
CLI to install and setup MCP servers

A command-line tool to install, manage, and setup MCP (Model Context Protocol) servers with Docker support.

Features

✨ Global CLI Tool: Install once with npm install -g and use the mcp command anywhere
🐳 Docker Support: Secure, sandboxed execution of MCP servers by default
🔍 Multi-Registry Search: Supports npm, GitHub, and Smithery registries
📦 GitHub URL Support: Install and uninstall directly from GitHub repositories
🛡️ Security First: Docker isolation by default, with optional direct execution
📋 Smart Configuration: Automatic detection and setup of MCP server configurations
🔧 Comprehensive Management: Install, uninstall, list, and get info about servers
⚡ Flexible Usage: Global installation recommended, npx available for one-time use
🤖 JSON Mode: Structured output for automation and programmatic use
⚙️ Configuration Arguments: Non-interactive setup with --args flag
📊 Multiple Log Levels: Verbose, debug, and quiet modes for different use cases

Quick Start

Install globally for the best experience:

# Install globally (recommended)
npm install -g @aurracloud/mcp-cli

# Now you can use the 'mcp' command anywhere
mcp install @modelcontextprotocol/server-filesystem -c claude
mcp list -c claude
mcp info @modelcontextprotocol/server-filesystem

Global Options

The MCP CLI supports global options that can be used with any command:

# Verbose output - shows detailed progress information
mcp install package-name -c claude --verbose

# Debug output - shows comprehensive debugging information
mcp install package-name -c claude --debug

# Quiet mode - suppresses all output except errors
mcp install package-name -c claude --quiet

# JSON mode commands automatically use quiet mode
mcp install package-name -c claude --json  # Automatically quiet
mcp info package-name --json              # Automatically quiet

Global Options:

-v, --verbose: Enable verbose output with detailed progress information
-d, --debug: Enable debug output with comprehensive debugging details
-q, --quiet: Suppress all output except errors (useful for scripting)

Note: JSON mode (--json) automatically enables quiet mode to prevent logging interference with structured output.

Installation

Global Installation (Recommended)

Install once and use everywhere:

# Install globally from npm
npm install -g @aurracloud/mcp-cli

# Now you can run the command from anywhere
mcp install package-name -c claude
mcp info package-name
mcp list -c claude
mcp uninstall package-name -c claude

One-time Use with npx

For occasional use without installation:

# Run commands directly without installing
npx @aurracloud/mcp-cli install package-name -c claude
npx @aurracloud/mcp-cli info package-name
npx @aurracloud/mcp-cli list -c claude
npx @aurracloud/mcp-cli uninstall package-name -c claude

Local Development

# Clone the repository
git clone https://github.com/aurracloud/mcp-cli.git
cd mcp-cli

# Install dependencies
npm install

# Run in development mode
npm run dev

# Or build and run
npm run build
npm start

Usage

Install an MCP Server

# Install with default options (uses Docker for security)
mcp install package-name -c claude

# Run the MCP server directly on host (not recommended)
mcp install package-name -c claude -d

# JSON mode for programmatic use
mcp install package-name -c claude --json

# Install with configuration arguments
mcp install package-name -c claude --args API_KEY=secret DEBUG_MODE=true

# JSON mode with configuration (for automation)
mcp install package-name -c claude --json --args API_KEY=secret --verbose=true

# Direct installation with configuration
mcp install package-name -c claude --direct --args FILESYSTEM_ROOT=/tmp

# Or use npx for one-time use
npx @aurracloud/mcp-cli install package-name -c claude

Installation Options:

-c, --client <client> (required): Specify the client (cursor, claude)
-d, --direct: Run directly on host instead of Docker (not recommended for security)
-j, --json: Output installation result in JSON format for programmatic use
-a, --args <args...>: Provide configuration arguments in key=value format

JSON Mode:

The --json flag enables structured output perfect for automation and scripting:

# Successful installation returns structured data
mcp install @modelcontextprotocol/server-filesystem -c cursor --json --args FILESYSTEM_ROOT=/tmp

{
  "success": true,
  "packageName": "@modelcontextprotocol/server-filesystem",
  "serverName": "@modelcontextprotocol/server-filesystem",
  "client": "cursor",
  "installationMode": "docker",
  "runtime": "node",
  "configuration": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "-e", "FILESYSTEM_ROOT=/tmp", "node:latest", "npx", "-y", "@modelcontextprotocol/server-filesystem"]
  },
  "environmentVariables": 1
}

# Errors also return structured JSON
mcp install nonexistent-package -c cursor --json

{
  "success": false,
  "error": "Package nonexistent-package does not exist on npm registry or PyPI.",
  "packageName": "nonexistent-package"
}

Configuration Arguments:

Use the --args flag to provide configuration without interactive prompts:

# Environment variables (key=value format)
mcp install server-name -c claude --args API_KEY=secret DATABASE_URL=postgres://...

# Command line arguments (--flag=value format)  
mcp install server-name -c claude --args --port=3000 --host=localhost

# Mixed configuration
mcp install server-name -c claude --args API_KEY=secret --verbose=true DEBUG_MODE=false

How it works:

The install command:

By default, runs MCP servers in a Docker container for better security and isolation
Will display a prominent warning if you choose to install directly with the -d flag
Automatically detects the server's connection type from the Smithery registry
- For HTTP connections, it will use the deployment URL
- For StdIO connections, it will use the recommended command and arguments if available
In JSON mode, automatically sets quiet logging to prevent output interference
Validates required configuration arguments when MCP server configuration is detected
Supports both Node.js (npm/npx) and Python (PyPI/uvx) packages

Uninstall an MCP Server

# Uninstall from a specific client
mcp uninstall package-name -c claude

# Also works with GitHub URLs (resolves to actual package name)
mcp uninstall https://github.com/owner/repo -c claude
mcp uninstall owner/repo -c claude

# Or use npx for one-time use
npx @aurracloud/mcp-cli uninstall package-name -c claude

The uninstall command now intelligently resolves GitHub URLs to the actual package name by:

Cloning the repository and reading the package.json to get the real package name
Trying multiple name variations to find the installed server
Providing helpful feedback about which names were tried if the server isn't found

List Installed MCP Servers

The list command displays all currently installed MCP servers for a specific client:

# List all MCP servers for Claude
mcp list -c claude

# List all MCP servers for Cursor
mcp list -c cursor

# Or use npx for one-time use
npx @aurracloud/mcp-cli list -c claude

Features:

Comprehensive Overview: Shows all installed MCP servers with their configurations
Installation Type Detection: Identifies Docker-based (sandboxed) vs direct installations
Configuration Details: Displays commands, arguments, and additional configuration
Summary Statistics: Provides counts by installation type
Helpful Tips: Includes guidance for managing servers
Error Handling: Clear messages for missing or invalid configurations

What it shows:

Server names and types
Command and arguments used to run each server
Whether servers run in Docker (safer) or directly on host
Additional configuration like environment variables, URLs, headers
Summary of installation types
Configuration file location and total server count

Get MCP Server Information

The info command provides comprehensive information about MCP servers by checking multiple registries with intelligent fallback:

# Get information about a server (checks npm, GitHub, and Smithery)
mcp info package-name

# Works with multiple formats
mcp info express                    # npm package
mcp info owner/repo                 # GitHub repository
mcp info @owner/repo               # npm scoped package format
mcp info https://github.com/owner/repo  # full GitHub URL

# JSON mode for programmatic use
mcp info package-name --json

# Or use npx for one-time use
npx @aurracloud/mcp-cli info package-name

# Set your Smithery API token for additional registry information
export SMITHERY_API_TOKEN=your-token

Options:

-j, --json: Output information in structured JSON format for automation

JSON Mode:

The --json flag provides structured output perfect for automation:

# Get structured information about a package
mcp info @modelcontextprotocol/server-filesystem --json

{
  "packageName": "@modelcontextprotocol/server-filesystem",
  "npm": {
    "found": true,
    "packageInfo": {
      "name": "@modelcontextprotocol/server-filesystem",
      "version": "0.6.2",
      "description": "MCP server for filesystem operations"
    },
    "isExecutable": true,
    "command": "npx -y @modelcontextprotocol/server-filesystem"
  },
  "git": {
    "found": true,
    "repoInfo": {
      "name": "servers",
      "fullName": "modelcontextprotocol/servers"
    },
    "isExecutable": true
  },
  "smithery": {
    "found": true,
    "serverDetails": {
      "qualifiedName": "@modelcontextprotocol/server-filesystem",
      "displayName": "Filesystem Server"
    }
  },
  "summary": {
    "foundInNpm": true,
    "foundInGit": true,
    "foundInSmitery": true,
    "hasMcpConfig": true
  }
}

How it works: 1. NPM Registry Check: First checks if the package exists on npm and is executable 2. GitHub Fallback: If not found on npm, searches GitHub repositories (supports all repository formats) 3. Smithery Registry: Always checks Smithery registry for additional MCP server information 4. Comprehensive Results: Displays information from all available sources with a summary

Upgrade MCP CLI

Keep your CLI tool up to date with the latest features and bug fixes:

# Upgrade to the latest version
mcp upgrade

# Or use npx (always gets latest version)
npx @aurracloud/mcp-cli upgrade

This command:

Automatically detects the package name from package.json
Checks the current version against the latest version on npm
Downloads and installs the latest version globally
Provides clear feedback on the upgrade process
Handles common errors like permission issues

Automation & Scripting

The MCP CLI is designed for both interactive use and automation. Use JSON mode and configuration arguments for seamless integration into scripts and CI/CD pipelines.

JSON Mode Examples

# Install with JSON output for automation
RESULT=$(mcp install @modelcontextprotocol/server-filesystem -c cursor --json --args FILESYSTEM_ROOT=/tmp)
echo $RESULT | jq '.success'  # true

# Check installation status
if echo $RESULT | jq -e '.success' > /dev/null; then
  echo "Installation successful"
  echo $RESULT | jq '.configuration.command'
else
  echo "Installation failed:"
  echo $RESULT | jq '.error'
fi

# Get package information programmatically
INFO=$(mcp info @modelcontextprotocol/server-filesystem --json)
echo $INFO | jq '.summary.foundInNpm'  # true
echo $INFO | jq '.npm.packageInfo.version'  # "0.6.2"

Batch Installation Script

#!/bin/bash

# List of servers to install
SERVERS=(
  "@modelcontextprotocol/server-filesystem"
  "@modelcontextprotocol/server-brave-search"
  "custom-server"
)

# Configuration for each server
declare -A SERVER_ARGS
SERVER_ARGS["@modelcontextprotocol/server-filesystem"]="FILESYSTEM_ROOT=/home/user"
SERVER_ARGS["@modelcontextprotocol/server-brave-search"]="BRAVE_API_KEY=your-key"
SERVER_ARGS["custom-server"]="API_KEY=secret DEBUG_MODE=true"

# Install each server
for server in "${SERVERS[@]}"; do
  echo "Installing $server..."
  
  args="${SERVER_ARGS[$server]}"
  if [ -n "$args" ]; then
    result=$(mcp install "$server" -c cursor --json --args $args)
  else
    result=$(mcp install "$server" -c cursor --json)
  fi
  
  if echo "$result" | jq -e '.success' > /dev/null; then
    echo "✅ $server installed successfully"
  else
    echo "❌ Failed to install $server:"
    echo "$result" | jq '.error'
  fi
done

CI/CD Integration

# GitHub Actions example
name: Install MCP Servers
on: [push]

jobs:
  install-servers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install MCP CLI
        run: npm install -g @aurracloud/mcp-cli
        
      - name: Install MCP Server
        run: |
          result=$(mcp install @modelcontextprotocol/server-filesystem -c cursor --json --args FILESYSTEM_ROOT=/workspace)
          echo "$result" | jq '.success' || exit 1
          
      - name: Verify Installation
        run: |
          info=$(mcp info @modelcontextprotocol/server-filesystem --json)
          echo "Installed version: $(echo "$info" | jq -r '.npm.packageInfo.version')"

Git Repository Integration

The CLI also includes utilities to check if GitHub repositories exist and whether they're executable via npx. This is particularly useful for MCP servers that are not published to npm but are available on GitHub:

import { checkGitRepoExistence, getGitNpxCommand, parseGitHubIdentifier } from './git';

// Check if a GitHub repository exists and is executable
const result = await checkGitRepoExistence('owner/repo');

if (result.exists) {
  console.log('Repository exists on GitHub!');
  
  if (result.packageInfo) {
    console.log('Repository has a package.json');
    
    if (result.isExecutable) {
      console.log('Repository is executable via npx');
      console.log(`Executable: ${result.executableName}`);
    }
  }
}

// Get the recommended command to run the repository
const npxCmd = await getGitNpxCommand('owner/repo');
if (npxCmd) {
  console.log(`Run with: ${npxCmd.command} ${npxCmd.args.join(' ')}`);
}

Supported Repository Formats

The git integration supports multiple repository identifier formats:

owner/repo - Simple owner/repository format
@owner/repo - npm scoped package format (@ symbol is automatically removed)
https://github.com/owner/repo - Full GitHub URL
https://github.com/owner/repo.git - Full GitHub URL with .git extension
git@github.com:owner/repo.git - SSH format

Features

Repository Existence Check: Verifies if a repository exists on GitHub using the GitHub API
Automatic Cloning: Clones repositories to temporary directories for analysis
Package.json Detection: Checks if the repository contains a valid package.json file
Executability Analysis: Determines if the package can be run via npx (has bin entries or start script)
Automatic Cleanup: Removes temporary cloned repositories after analysis
Rich Repository Information: Provides detailed information about the repository including description, language, license, and topics

Example Usage

# Check a repository using the example script
npx ts-node examples/check-git-repo.ts facebook/create-react-app
npx ts-node examples/check-git-repo.ts https://github.com/vercel/pkg
npx ts-node examples/check-git-repo.ts @microsoft/vscode
npx ts-node examples/check-git-repo.ts microsoft/vscode

See the examples in examples/check-git-repo.ts for more details.

Development

Building the Project

npm run build

Adding New Commands

Create a new file in the src/commands/ directory
Implement your command function
Import and register the command in src/index.ts

Releasing (Maintainers Only)

We use automated releases with GitHub Actions. Use the interactive release script:

# Interactive release (recommended)
npm run release

# Or quick releases
npm run release:patch    # Bug fixes
npm run release:minor    # New features  
npm run release:major    # Breaking changes

This will automatically: