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 │
                    └─────────────────┘

🚀 Quick Start

Option 1: Web Interface (Recommended)

1. Start the Backend API:

   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:

   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

📱 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

🛠️ 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:

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

2. Backend Setup:

   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:

   cd frontend
   npm install
   npm run dev
   

4. CLI Setup:

   # 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

🌐 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

🔧 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"
      }
    }
  }
}

🛡️ 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

🚨 Troubleshooting

Common Issues

Issue	Solution
"No configuration found"	Run setup wizard or ensure Claude Desktop has been run once
"Backend connection failed"	Ensure backend is running on port 8001
"npm not available"	Install Node.js from https://nodejs.org/
"pip not available"	Install Python from https://python.org/
"Permission denied"	Check file permissions or run with appropriate privileges

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

🏢 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!