MC-Manager is a self-hosted Minecraft server management panel that lets you create, configure, monitor, and control multiple Minecraft server instances — all from a modern dark-themed web UI. Each server runs as an isolated Docker container, giving you full control over lifecycle, configuration, backups, plugins, mods, and player management.

✨ Features

Server Management

Multi-instance — Run multiple Minecraft servers simultaneously, each in its own Docker container
Server types — Vanilla, Bukkit (Paper/Spigot/Purpur), Forge, and Fabric
Lifecycle control — Start, stop, restart, and delete server instances with real-time status tracking
Auto-start & auto-restart — Configurable restart policies per server

Live Console

Real-time log streaming — Tail server stdout/stderr directly in the browser
Command execution — Send commands to the server console from the UI

Configuration

server.properties editor — Edit Minecraft configuration per instance
JVM tuning — Configure memory allocation (min/max heap) and custom JVM arguments
Port management — Custom host port mappings for game and RCON ports

Backups

Manual backups — Create on-demand backups of world data
Scheduled backups — Cron-based automated backups with configurable retention
Point-in-time restore — Restore any backup to roll back a server's world

Extensions

Plugins (Bukkit-type servers) — Upload, install, remove, enable/disable plugin JARs
Mods (Forge/Fabric servers) — Upload, install, remove, enable/disable mod JARs

Player Management

Whitelist — Add/remove players from the server whitelist
Operators — Grant/revoke operator privileges
Bans — Ban/unban players
Online players — View currently connected players

Security & Administration

Role-based access control — Granular permissions (resource:action format) with wildcard support
Dual-token JWT auth — 1-hour access tokens + 7-day refresh tokens in HTTP-only cookies
Mandatory 2FA — Email-based two-factor authentication on every login
Account lockout — Automatic lockout after 5 failed login attempts (30-minute cooldown)
Audit logging — Every mutation is logged with previous/new values and client IP
Input sanitization — All inputs sanitized server-side; parameterized database queries only

🛠️ Tech Stack

Layer	Technology
Framework	Next.js 16 (App Router)
UI	React 19, TypeScript 5
Styling	Tailwind CSS 4
Database	MongoDB via Mongoose 9
Containers	Docker via dockerode
Auth	JWT (jsonwebtoken), bcryptjs
Email	Microsoft Graph API + SMTP (nodemailer) fallback
Scheduling	node-cron
Icons	Lucide React

📋 Prerequisites

Node.js 20+
MongoDB 6+ (local or Atlas)
Docker Engine with the Docker socket accessible (/var/run/docker.sock)
Docker image: itzg/minecraft-server (pulled automatically, or specify a custom image per server)

🚀 Getting Started

1. Clone the repository

git clone https://github.com/your-org/mc-manager.git
cd mc-manager

2. Install dependencies

npm install

3. Configure environment variables

Create a .env.local file in the project root:

# Database
MONGODB_URI=mongodb://localhost:27017/mc-manager

# Authentication
JWT_SECRET=your-secure-jwt-secret-here
JWT_REFRESH_SECRET=your-secure-refresh-secret-here
TWO_FACTOR_SECRET=your-secure-2fa-secret-here
NODE_ENV=development

# Docker
MC_SERVERS_PATH=/opt/mc-servers
DOCKER_SOCKET=/var/run/docker.sock

# Email — Microsoft Graph API (primary)
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
EMAIL_FROM=noreply@yourdomain.com

# Email — SMTP fallback
SMTP_HOST=smtp.yourdomain.com
SMTP_PORT=587
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password

# CORS (production)
ALLOWED_ORIGINS=https://your-domain.com

4. Prepare the server data directory

sudo mkdir -p /opt/mc-servers
sudo chown $USER:$USER /opt/mc-servers

5. Seed the database

Run the seed script to create default roles and the initial admin user:

npm run seed

You will be prompted to enter an email and password for the admin account.

6. Start the development server

npm run dev

Open http://localhost:3000 and log in with your admin credentials.

📁 Project Structure

src/
├── app/                        # Next.js App Router
│   ├── (app)/                  # Authenticated app pages
│   │   ├── dashboard/          # Dashboard overview
│   │   ├── servers/            # Server list & detail pages
│   │   │   └── [id]/           # Per-server views
│   │   │       ├── backups/    #   Backup management
│   │   │       ├── configuration/ # server.properties & JVM config
│   │   │       ├── console/    #   Live console
│   │   │       ├── files/      #   File browser
│   │   │       ├── logs/       #   Log viewer
│   │   │       ├── mods/       #   Mod management (Forge/Fabric)
│   │   │       ├── players/    #   Player management
│   │   │       └── plugins/    #   Plugin management (Bukkit)
│   │   ├── users/              # User management
│   │   ├── roles/              # Role & permission management
│   │   └── audit/              # Audit log viewer
│   ├── api/                    # API routes (REST)
│   └── login/                  # Login page
├── components/                 # Shared UI components
│   ├── templates/              # Reusable CRUD templates
│   └── ui/                     # Base UI primitives
├── contexts/                   # React context providers
├── hooks/                      # Custom React hooks
├── lib/                        # Server-side utilities
│   ├── auth.ts                 # JWT, 2FA, sessions, permissions
│   ├── mongodb.ts              # Cached Mongoose connection
│   ├── models.ts               # Mongoose schemas & models
│   ├── docker.ts               # Docker client & container ops
│   ├── backup-scheduler.ts     # Cron-based backup scheduling
│   ├── audit.ts                # Audit log helpers
│   ├── input-validation.ts     # Sanitization & validation
│   ├── date-utils.ts           # Date formatting utilities
│   ├── email.ts                # Email dispatch (Graph + SMTP)
│   └── email-graph.ts          # Microsoft Graph API email client
└── types/                      # TypeScript interfaces

🔐 Permissions

Permissions follow a resource:action format. The Admin role receives *:* (full access).

Resource	Actions
`servers`	`view`, `create`, `edit`, `delete`, `start`, `stop`, `restart`, `console`
`backups`	`view`, `create`, `restore`, `delete`
`plugins`	`view`, `install`, `remove`, `toggle`
`mods`	`view`, `install`, `remove`, `toggle`
`players`	`view`, `whitelist`, `op`, `ban`
`users`	`view`, `create`, `edit`, `delete`
`roles`	`view`, `create`, `edit`, `delete`
`audit`	`view`

🐳 Docker Architecture

Each Minecraft server runs as an isolated Docker container using the itzg/minecraft-server image (or a custom image).

Volume layout per server:

/opt/mc-servers/{serverId}/
├── server.properties       # Minecraft configuration
├── world/                  # World data (backed up)
├── plugins/                # Bukkit-type servers only
├── mods/                   # Forge/Fabric servers only
├── logs/                   # Server logs
└── backups/                # Backup archives

Container naming convention: mc-{serverId}

🎮 Server Types

Type	Examples	Plugins	Mods
Vanilla	Official Mojang server	✗	✗
Bukkit	Paper, Spigot, Purpur	✓	✗
Forge	Forge mod loader	✗	✓
Fabric	Fabric mod loader	✗	✓

📦 Scripts

Command	Description
`npm run dev`	Start development server (port 3000)
`npm run build`	Create production build
`npm run start`	Start production server
`npm run lint`	Run ESLint
`npm run seed`	Seed database with default roles and admin user

🔒 Security Highlights

Server-side authority — All permission checks are enforced server-side; client-side checks are UI hints only
HTTP-only cookies — Tokens are never exposed to JavaScript
Input sanitization — All user input is sanitized via sanitizeObject() before processing
Parameterized queries — No string concatenation in database queries
CORS enforcement — Origin validation in production
Security headers — X-Frame-Options: DENY, X-Content-Type-Options: nosniff, strict Referrer-Policy, and restrictive Permissions-Policy
Comprehensive audit trail — Every create, update, and delete is logged with user info, client IP, and value diffs

License

This project is private and not licensed for redistribution.