Smithery CLI

What is Smithery CLI about?

Installs, uninstalls, inspects, runs, and builds MCP servers directly from the terminal. It works with any AI client and provides interactive or scripted workflows for server lifecycle management.

How to use Smithery CLI?

1. Installation – preferred global usage:

   npm install -g @smithery/cli
   

   or run one‑off commands without installing:

   npx @smithery/cli <command>
   

2. Basic workflow – after logging in with smithery login (API key required), you can:
   • Install a server: smithery install <server> [--client <name>] [--config <json>]
   • Uninstall a server: smithery uninstall <server> [--client <name>]
   • List installed servers: smithery list [--client <name>]
   • Run a server: smithery run <server-id> [--config <json>]
   • Develop with hot‑reload: smithery dev [entryFile] [--port <port>] [--key <apikey>]
   • Build for production: smithery build [entryFile] [--out <outfile>] [--transport <type>]
   • Test in a web playground: smithery playground [--port <port>]
3. Flags – --help shows usage, --verbose prints detailed logs.

Key Features

• Client‑agnostic: works with any supported AI client.
• Interactive prompts for selection or fully scripted via flags.
• Development server with hot‑reload and optional tunnel.
• Production build supporting shttp or stdio transports.
• Web‑based playground for rapid testing.
• Global install or on‑the‑fly usage through npx.
• Built‑in login handling for Smithery API keys.

Use Cases

• Rapid prototyping of new MCP services without manual setup.
• CI/CD pipelines that install, configure, and run MCP servers automatically.
• Multi‑client environments where the same server must be deployed to different AI backends.
• Local testing of server behavior via the interactive playground.
• Production deployment by building a single‑file bundle (.cjs) ready for containerization.

FAQ

Q: Do I need to install Node.js? A: Yes, NodeJS version 20 or newer is required.

Q: How do I authenticate? A: Run smithery login and provide your Smithery API key; the key is stored for subsequent commands.

Q: Can I bypass interactive prompts? A: Absolutely. Use flags like --client, --config, and --no-open to run commands non‑interactively.

Q: What transport options are available for the built server? A: shttp (default) and stdio.

Q: How do I expose a server to the internet for testing? A: Use the dev command with a tunnel (provide --key if required) or the playground command which launches a web UI.

Smithery CLI

The Smithery registry installer and manager for Model Context Protocol (MCP) servers, designed to be client-agnostic.

Requirements

• NodeJS version 20 or above

Installation

Install globally for easier usage:

npm install -g @smithery/cli

Usage

smithery <command>

Or run directly without installation:

npx @smithery/cli <command>

Available Commands

• install <server> - Install a server (interactive client selection)
  • --client <name> - Specify the AI client (skips selection)
  • --config <json> - Provide configuration data as JSON (skips prompts)
• uninstall <server> - Uninstall a server (interactive client selection)
  • --client <name> - Specify the AI client (skips selection)
• inspect <server-id> - Inspect a server interactively
• run <server-id> - Run a server
  • --config <json> - Provide configuration for the server
• list - List installed servers (interactive client selection)
  • --client <name> - Specify the AI client (skips selection)
• search [term] - Search for servers in the Smithery registry (interactive)
• login - Login with an API key (interactive)
• dev [entryFile] - Start development server with hot-reload and tunnel
  • --port <port> - Port to run the server on (default: 8081)
  • --key <apikey> - Provide an API key
  • --no-open - Don't automatically open the playground
  • --prompt <prompt> - Initial message to start the playground with
  • -c, --config <path> - Path to config file (default: auto-detect smithery.config.js)
• build [entryFile] - Build MCP server for production
  • -o, --out <outfile> - Output file path (default: .smithery/index.cjs)
  • --transport <type> - Transport type: shttp or stdio (default: shttp)
  • -c, --config <path> - Path to config file (default: auto-detect smithery.config.js)
• playground - Open MCP playground in browser
  • --port <port> - Port to expose (default: 8081)
  • --key <apikey> - Provide an API key
  • Can pass command after -- separator
• --help - Show help message
• --verbose - Show detailed logs for debugging

Examples

# Install a server (interactive client selection)
smithery install exa

# Install a server for specific client (skips selection)
smithery install exa --client claude

# Install a server with pre-configured data (skips prompts)
smithery install exa --client claude --config '{"exaApiKey":"you_api_key"}'

# Remove a server (interactive client selection)
smithery uninstall exa

# Remove a server from specific client (skips selection)
smithery uninstall exa --client claude

# List installed servers (interactive)
smithery list

# List installed servers for claude
smithery list --client claude

# Search for servers in the registry
smithery search "web search"

# Search interactively (prompts for term)
smithery search

# Inspect a specific server from smithery's registry
smithery inspect exa

# Run a server with configuration
smithery run exa --config '{"key":"value"}'

# Login and set API key
smithery login

# Start development server with hot-reload
smithery dev
smithery dev server.ts --port 3000

# Build server for production
smithery build
smithery build server.ts --out dist/server.cjs --transport stdio

# Open playground in browser
smithery playground
smithery playground --port 3001 -- node dist/server.js

# Show help menu
smithery --help

# Install with verbose logging for debugging
smithery install mcp-obsidian --client claude --verbose

Important Notes

• Use login command to set your Smithery API key (required for some operations)
• Remember to restart your AI client after installing or uninstalling servers
• Use the inspect command for interactive server testing
• Run without arguments to see the help menu
• Use --verbose flag for detailed logs when troubleshooting
• The dev command provides hot-reload for MCP server development
• Use playground to test your MCP servers in an interactive web interface

Development

This guide will help you get started with developing for @smithery/cli.

Getting Started

1. Clone the repository:

   git clone https://github.com/smithery-ai/cli
   cd cli
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Development Commands

# List installed servers
npx . list --client claude

# Search for servers
npx . search obsidian

# Inspect a specific server
npx . inspect <server-id>

# Install a server
npx . install <server-name> --client <client-name>

# Run with verbose logging
npx . <command> --verbose

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.