CLI Reference

MCP Hangar provides a comprehensive command-line interface for managing MCP servers.

Installation

pip install mcp-hangar
# or
uv pip install mcp-hangar

Synopsis

mcp-hangar [OPTIONS] COMMAND [ARGS]...

Global Options

These options are available for all commands:

Commands

init

Interactive setup wizard for MCP Hangar. Guides you through MCP server selection and configuration in under 5 minutes.

Synopsis

mcp-hangar init [OPTIONS]

Options

MCP Server Bundles

Examples

# Interactive setup
mcp-hangar init

# Install starter bundle
mcp-hangar init --bundle starter

# Install specific mcp_servers
mcp-hangar init --mcp-servers filesystem,github,sqlite

# Non-interactive with developer bundle
mcp-hangar init -y --bundle developer

# Custom config location
mcp-hangar init --config-path ~/my-config.yaml

# Skip Claude Desktop integration
mcp-hangar init --skip-claude

What It Does

1. Detects Claude Desktop installation
2. Presents MCP server categories for selection
3. Collects required configuration (API keys, paths)
4. Generates config.yaml file
5. Updates Claude Desktop configuration
6. Shows next steps

status

Display health dashboard of all configured MCP servers with real-time updates.

Synopsis

mcp-hangar status [OPTIONS] [MCP_SERVER]

Arguments

Options

MCP Server States

Examples

# Show all mcp_servers
mcp-hangar status

# Watch mode with live updates
mcp-hangar status --watch

# Faster refresh rate
mcp-hangar status -w -i 0.5

# Show detailed information
mcp-hangar status --details

# Single mcp_server details
mcp-hangar status github

# JSON output for scripting
mcp-hangar --json status

Output Columns

Standard view:

• MCP Server name
• State indicator
• Tools count

Detailed view (--details):

• MCP Server name
• State indicator
• Mode (subprocess/docker/remote)
• Tools count
• Memory usage
• Uptime

add

Add a MCP server from the MCP Registry to your configuration.

Synopsis

mcp-hangar add [OPTIONS] NAME

Arguments

Options

Available MCP servers

Examples

# Add by exact name
mcp-hangar add github

# Search for mcp_servers
mcp-hangar add --search database

# Skip confirmation
mcp-hangar add filesystem -y

# Add without hot-reload
mcp-hangar add postgres --no-reload

Configuration Prompts

When adding a MCP server that requires configuration, you'll be prompted for:

• Secrets (API keys, tokens): Hidden input, stored securely
• Paths (directories, files): Path validation
• Text (URLs, names): Standard input

Environment variables are detected automatically. If GITHUB_TOKEN is set, you'll be asked whether to use it.

remove

Remove a MCP server from your configuration.

Synopsis

mcp-hangar remove [OPTIONS] NAME

Arguments

Options

Examples

# Remove with confirmation
mcp-hangar remove github

# Remove without confirmation
mcp-hangar remove filesystem -y

# Remove from config but keep running
mcp-hangar remove postgres --keep-running

Behavior

1. Validates MCP server exists in configuration
2. Prompts for confirmation (unless -y)
3. Stops running instance (unless --keep-running)
4. Removes from config.yaml
5. Attempts hot-reload of server

serve

Start the MCP Hangar server. This is the default command when no subcommand is specified.

Synopsis

mcp-hangar serve [OPTIONS]
# or simply:
mcp-hangar [OPTIONS]

Options

Transport Modes

stdio (default)

JSON-RPC over stdin/stdout. Used by Claude Desktop and similar clients.

mcp-hangar serve
mcp-hangar --config config.yaml serve

HTTP

HTTP server with Streamable HTTP transport. Used by LM Studio and web clients.

mcp-hangar serve --http
mcp-hangar serve --http --port 9000
mcp-hangar serve --http --host 127.0.0.1 --port 8080

HTTP Endpoints

When running in HTTP mode:

Log Levels

• DEBUG - Detailed debugging information
• INFO - General operational information (default)
• WARNING - Warning messages
• ERROR - Error messages only
• CRITICAL - Critical errors only

Examples

# stdio mode (for Claude Desktop)
mcp-hangar serve

# HTTP mode on default port
mcp-hangar serve --http

# HTTP mode with custom port
mcp-hangar serve --http -p 9000

# With debug logging
mcp-hangar serve --log-level DEBUG

# With log file
mcp-hangar serve --log-file /var/log/mcp-hangar.log

# JSON logs for log aggregation
mcp-hangar serve --json-logs

# Full production setup
mcp-hangar serve --http --host 0.0.0.0 --port 8000 \
  --log-level INFO --json-logs --log-file /var/log/mcp.log

completion

Generate shell completion scripts for tab-completion support.

Synopsis

mcp-hangar completion COMMAND

Subcommands

Installation

Bash

# System-wide
mcp-hangar completion bash | sudo tee /etc/bash_completion.d/mcp-hangar

# User-only
mcp-hangar completion bash >> ~/.bashrc

Zsh

# Add to fpath
mcp-hangar completion zsh > ~/.zfunc/_mcp-hangar

# Add to .zshrc if not already present:
# fpath=(~/.zfunc $fpath)
# autoload -Uz compinit && compinit

Fish

mcp-hangar completion fish > ~/.config/fish/completions/mcp-hangar.fish

Auto-install

# Detect shell and install
mcp-hangar completion install

# Specify shell
mcp-hangar completion install zsh

Configuration File

Default Locations

The CLI searches for configuration in this order:

1. --config option
2. MCP_CONFIG environment variable
3. ~/.config/mcp-hangar/config.yaml
4. ./config.yaml (current directory)

Example Configuration

mcp_servers:
  filesystem:
    mode: subprocess
    command:
      - npx
      - -y
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/documents"

  github:
    mode: subprocess
    command:
      - npx
      - -y
      - "@modelcontextprotocol/server-github"
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}

  my-api:
    mode: remote
    endpoint: https://api.example.com/mcp

logging:
  level: INFO
  json_format: false

event_store:
  enabled: true
  driver: sqlite
  path: data/events.db

Environment Variables

Exit Codes

See Also

• Quick Start Guide
• HTTP Transport Guide