MCP Manager

A comprehensive full-stack application for managing Model Context Protocol (MCP) servers for Claude Desktop with intelligent setup, auto-scanning, enhanced error handling, and a modern web interface.

✨ Features

🖥️ Full-Stack Architecture

• CLI Tool: Enhanced command-line interface with setup wizard and auto-scanning
• Web Interface: Modern React frontend with real-time server management
• REST API: FastAPI backend with comprehensive endpoints
• Cross-Platform: Works on Windows, macOS, and Linux

🚀 Core Functionality

• Server Discovery: Automatically finds available MCP servers from multiple sources
• Easy Installation: Install servers with automatic dependency management
• Configuration Management: Safely manage Claude Desktop configuration with atomic operations
• Backup & Restoration: Built-in backup and restore functionality
• Real-time Monitoring: Live server status and health monitoring
• Web Dashboard: Beautiful, responsive web interface for all operations

🔧 Enhanced Features

• 🧙‍♂️ Setup Wizard: Interactive guided onboarding for new users
• 🔍 Auto-Scanning: Automatic discovery of new MCP servers and updates
• 🛠️ Smart Error Handling: Auto-fix suggestions and intelligent recovery
• 📢 Notification System: Stay informed about updates and recommendations
• 💊 Health Monitoring: System diagnostics and dependency checking
• 🎯 Personalized Recommendations: Intelligent server suggestions
• ⭐ GitHub Integration: Support for awesome-mcp-servers repositories

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Web Frontend  │    │   REST API      │    │   CLI Tool      │
│   (React)       │────│   (FastAPI)     │────│   (Python)      │
│   Port 3001     │    │   Port 8001     │    │   Direct Access │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │  Core Services  │
                    │                 │
                    │ • Config Mgmt   │
                    │ • Server Sources│
                    │ • Notifications │
                    │ • Health Monitor│
                    │ • GitHub Parser │
                    │ • Error Handler │
                    └─────────────────┘

📱 Web Interface Features

🎛️ Dashboard

• Server installation status overview
• System health monitoring
• Quick access to common operations
• Real-time connection status

🔧 Server Management

• Browse 60+ available MCP servers
• Install/uninstall servers with one click
• View detailed server information
• Category and tag-based filtering

📊 System Monitoring

• Health score and system diagnostics
• Dependency status checking
• Configuration validation
• Performance metrics

⚙️ Configuration

• Visual Claude Desktop config management
• Backup and restore operations
• Environment settings
• API configuration

📢 Notifications

• Real-time alerts and updates
• Priority-based notification system
• Action items with one-click solutions
• Notification history and management

📋 CLI Commands

Core Commands

# Server Management
./mcp-manager list                    # Show installed servers
./mcp-manager available              # Show available servers
./mcp-manager backup                 # Create configuration backup

# Enhanced Commands
./mcp-manager setup                  # 🆕 Interactive setup wizard
./mcp-manager scan                   # 🆕 Scan for updates and new servers
./mcp-manager diagnose               # 🆕 Run system health check
./mcp-manager notifications          # 🆕 View alerts and updates
./mcp-manager status                 # Enhanced with notifications

Command Options

--config-path <path>     # Override default config location
--verbose                # Detailed output
--json                   # Output in JSON format
--no-cache              # Skip cache for fresh data
--force                 # Skip confirmation prompts

🌐 API Endpoints

The FastAPI backend provides comprehensive REST endpoints:

• GET /api/health: Health check
• GET /api/servers/available: List available servers
• GET /api/servers/installed: List installed servers
• POST /api/servers/install: Install a server
• DELETE /api/servers/{name}: Uninstall a server
• GET /api/system/status: System health status
• POST /api/system/scan: Run system scan
• GET /api/notifications/: Get notifications
• GET /api/analytics/overview: Analytics dashboard

Full API documentation available at: http://localhost:8001/docs

🛡️ Safety Features

Atomic Operations

• All configuration changes use atomic file operations
• Temporary files prevent corruption during writes
• Automatic rollback on any failure

Automatic Backups

• Backups created before any destructive operation
• Timestamped backup files for easy identification
• Easy restoration through web interface or CLI

Comprehensive Validation

• JSON schema validation for all configuration changes
• Server name validation (alphanumeric with hyphens/underscores)
• Environment variable validation
• Pre-flight checks before operations

🏢 Technology Stack

Frontend

• React 18 with TypeScript
• Vite for fast development and building
• TailwindCSS for modern styling
• Tanstack Query for API state management
• React Router for navigation

Backend

• FastAPI for modern Python API development
• Pydantic for data validation
• Uvicorn for ASGI server
• Requests for HTTP client functionality

CLI Tool

• Python 3.8+ with cross-platform support
• Rich for beautiful terminal output
• Click for CLI framework
• GitPython for repository operations

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Commit changes (git commit -m 'Add amazing feature')
7. Push to branch (git push origin feature/amazing-feature)
8. Open a Pull Request

📄 License

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

⭐ Key Benefits

• Zero Learning Curve: Setup wizard eliminates configuration complexity
• Modern Interface: Beautiful web UI alongside powerful CLI
• Stay Current: Never miss important updates or useful new servers
• Reduce Errors: Automatic error detection and intelligent recovery
• Save Time: Smart recommendations and one-click solutions
• Production Ready: Comprehensive safety features and error handling
• Cross-Platform: Works seamlessly on Windows, Mac, and Linux

Ready to get started?

• Web Interface: Run the backend and frontend, then visit http://localhost:3001
• CLI Tool: Run ./mcp-manager setup for a guided setup experience!

🚀 Quick Start

Option 1: Web Interface (Recommended)

1. Start the Backend API:

   Copy

   cd backend
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   pip install -r requirements.txt
   uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

2. Start the Frontend:

   Copy

   cd frontend
   npm install
   npm run dev

3. Access the Web Interface: Open http://localhost:3001 in your browser

Option 2: CLI Tool

# Clone and set up
git clone <your-repo-url>
cd mcp-manager
chmod +x mcp-manager

# Run interactive setup (recommended for first-time users)
./mcp-manager setup

🛠️ Development Setup

Prerequisites

• Python 3.8+ (required)
• Node.js 16+ and npm (for frontend)
• Git (for version control)

Full Development Environment

1. Clone the Repository:

   Copy

   git clone <your-repo-url>
   cd mcp-manager

2. Backend Setup:

   Copy

   cd backend
   python -m venv venv
   source venv/bin/activate  # Windows: venv\Scripts\activate
   pip install -r requirements.txt
   uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

3. Frontend Setup:

   Copy

   cd frontend
   npm install
   npm run dev

4. CLI Setup:

   Copy

   # Make CLI executable
   chmod +x mcp-manager
   
   # Run setup wizard
   ./mcp-manager setup

Available Scripts

Backend

uvicorn app.main:app --reload          # Development server
uvicorn app.main:app --host 0.0.0.0    # Production server
python -m pytest                       # Run tests

Frontend

npm run dev         # Development server
npm run build       # Production build
npm run preview     # Preview production build
npm run lint        # Lint code

🔧 Configuration

MCP Manager automatically discovers your Claude Desktop configuration:

• Windows: %APPDATA%\\Claude\\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration Schema

{
  "mcpServers": {
    "server-name": {
      "command": "executable-path",
      "args": ["arg1", "arg2"],
      "env": {
        "KEY": "value"
      }
    }
  }
}

🚨 Troubleshooting

Common Issues

Getting Help

# CLI Diagnostics
./mcp-manager diagnose
./mcp-manager status --verbose
./mcp-manager notifications --all

# Web Interface
# Visit http://localhost:3001/system for health dashboard
# Check browser console for frontend errors
# Review backend logs for API issues

Emergency Recovery

If your configuration becomes corrupted:

# List available backups
ls ~/.config/Claude/mcp_manager_backups/

# CLI recovery
./mcp-manager status --verbose

# Web interface recovery
# Navigate to System > Configuration for backup restore