MCP Registry CLI

A command-line interface for navigating and managing servers from the Model Context Protocol (MCP) registry.

Features

• 🔍 Browse MCP servers with intelligent pagination (30 servers per page)
• 📊 Filter and sort servers by status, name, description
• 📋 View detailed information including packages and repositories
• 📦 Install servers via CLI with npm/pip support
• 🎨 Rich terminal UI with colors, tables, and beautiful formatting
• ⌨️ Interactive navigation with full keyboard support
• 🚀 Smart pagination with left/right arrow keys and p/n shortcuts
• 🔗 Direct API access to MCP Registry

Installation

📦 Available on PyPI: https://pypi.org/project/mcp-registry-cli/

Prerequisites

• Python 3.8 or higher
• pip package manager

Recommended: Using Virtual Environment

# Create and activate virtual environment
python3 -m venv mcp-registry-env
source mcp-registry-env/bin/activate  # On Windows: mcp-registry-env\Scripts\activate

# Install from PyPI
pip install mcp-registry-cli

System-wide Installation

# Install directly from PyPI
pip install mcp-registry-cli

From Source (Development)

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

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

# Or with development dependencies
pip install -e ".[dev]"

Quick Start

Interactive Mode (Recommended)

# Start interactive CLI with keyboard navigation
mcp-registry-cli

# Alternative ways to start interactive mode
mcp-registry --interactive
mcp-registry interactive

Interactive Controls:

• ↑/↓ or k/j - Navigate servers within current page
• ←/→ or p/n - Navigate between pages (30 servers per page)
• Enter - View detailed server information
• i - Install selected server
• / - Live filter - Type to filter current page in real-time
• Esc - Exit live filter mode
• s - Search servers by name or description (API search)
• f - Filter servers by status (active, inactive, deprecated)
• c - Clear all filters and search
• r - Refresh server list
• h - Show/hide help panel
• q - Quit application

Live Filter Feature:

• Real-time filtering: Press / to filter servers as you type
• Instant results: No API calls - filters current page immediately
• Smart matching: Searches both server names and descriptions
• Easy editing: Use Backspace to refine, Enter to accept, Esc to cancel
• Visual feedback: Filter text shown in header with live result count

Pagination Features:

• Smart page navigation: 30 servers per page with intuitive controls
• Page indicators: Shows current page with "+" when more pages available (e.g., "Page 2+")
• Cross-platform: Arrow keys work on Windows, macOS, and Linux
• Fallback support: Works in any terminal, with or without Rich library

Command Line Mode

# List first 10 servers
mcp-registry list --limit 10

# Search for GitHub-related servers
mcp-registry list --search github

# Show detailed information about a server
mcp-registry show io.github.domdomegg/airtable-mcp-server

# Preview installation commands
mcp-registry install io.github.domdomegg/airtable-mcp-server --dry-run

# Install a server (requires appropriate package manager)
mcp-registry install io.github.domdomegg/airtable-mcp-server

Command Reference

List Servers

mcp-registry list [OPTIONS]

Options:
  --limit INTEGER         Number of servers to display (default: 30)
  --cursor TEXT          Pagination cursor for next page
  --search TEXT          Search servers by name or description
  --status TEXT          Filter by status (active, inactive, deprecated)
  --sort [name|status|description]  Sort by field (default: name)
  --reverse              Reverse sort order

Show Server Details

mcp-registry show <server-name>

Example:
mcp-registry show ai.waystation/gmail

Install Server

mcp-registry install <server-name> [OPTIONS]

Options:
  --package-manager [npm|pip|auto]  Package manager to use (default: auto)
  --dry-run                        Show commands without executing

Examples

Explore the Registry

# List all active servers
mcp-registry list --status active

# Find database-related servers
mcp-registry list --search database --limit 5

# Browse with pagination (30 servers per page)
mcp-registry list --limit 30
# Use the cursor from output for next page
mcp-registry list --cursor <next-cursor>

Get Server Information

# View comprehensive server details
mcp-registry show com.pga/pga-golf

# Check available installation packages
mcp-registry show io.github.DeanWard/HAL

Install Servers

# Preview installation
mcp-registry install xcodebuildmcp --dry-run

# Install with specific package manager
mcp-registry install hal-mcp --package-manager npm

# Auto-detect and install
mcp-registry install reddit-research-mcp

Programmatic Usage

from mcp_registry_cli.api import MCPRegistryAPI

# Initialize API client
api = MCPRegistryAPI()

# List servers
result = api.list_servers(limit=10)
for server in result['servers']:
    print(f"{server.name}: {server.description}")

# Get server details
server = api.get_server_details("ai.waystation/gmail")
print(f"Status: {server.status}")
if server.packages:
    print("Available packages:")
    for pkg in server.packages:
        print(f"  - {pkg.get('registry')}: {pkg.get('package')}")

# Search servers
result = api.search_servers("github", limit=5)
print(f"Found {len(result['servers'])} GitHub-related servers")

Troubleshooting

Virtual Environment Issues

If you encounter permission errors, ensure you're using a virtual environment:

python3 -m venv mcp-registry-env
source mcp-registry-env/bin/activate
pip install --upgrade pip
pip install mcp-registry-cli

Package Installation

If server installation fails, check that you have the required package manager:

• npm servers: Ensure Node.js and npm are installed
• pip servers: Ensure Python and pip are available
• Use --dry-run to preview commands before execution

API Issues

If you encounter API errors:

• Check your internet connection
• The MCP Registry API may be temporarily unavailable
• Try reducing the --limit parameter

Development

Setup Development Environment

# Clone repository
git clone https://github.com/loretoparisi/mcp-registry-cli.git
cd mcp-registry-cli

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

Development Commands

# Run tests
pytest

# Format code
black src/

# Type checking
mypy src/

# Test CLI locally
python3 -m src.mcp_registry_cli.cli --help

Requirements

• Python 3.8+
• click >= 8.0.0
• requests >= 2.25.0
• rich >= 12.0.0
• tabulate >= 0.9.0

License

This project is licensed under the MIT License - see the LICENSE file for details.

License Summary

• ✅ Free to use for commercial and non-commercial purposes
• ✅ Modify and distribute as needed
• ✅ Include in your own projects
• ✅ Must include copyright notice

Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Author

Loreto Parisi - [email protected]

Acknowledgments

• Built for the Model Context Protocol (MCP) ecosystem
• Uses the official MCP Registry API
• Powered by Rich for beautiful terminal output