https://github.com/nexuls/mcworker-go
🌍 Create, manage, and monitor Minecraft servers from your terminal — supports Paper, Fabric, Forge, and more.
https://github.com/nexuls/mcworker-go
bubbletea cli cli-tool minecraft-server
Last synced: 12 days ago
JSON representation
🌍 Create, manage, and monitor Minecraft servers from your terminal — supports Paper, Fabric, Forge, and more.
- Host: GitHub
- URL: https://github.com/nexuls/mcworker-go
- Owner: nexuls
- License: mit
- Created: 2026-01-20T07:32:49.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-26T17:13:56.000Z (6 months ago)
- Last Synced: 2026-07-12T19:43:29.225Z (12 days ago)
- Topics: bubbletea, cli, cli-tool, minecraft-server
- Language: Go
- Homepage:
- Size: 529 KB
- Stars: 2
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# MineWorker
[](https://go.dev/)
[](LICENSE)
> [!WARNING]
> 🚧 **Under Construction** — This project is currently in active development. Features and APIs may change without notice.
A terminal-based Minecraft server management tool built with Go and [Bubble Tea](https://github.com/charmbracelet/bubbletea).
## Features
- 🌍 **World Management** — Create, configure, and manage multiple Minecraft server worlds with an intuitive form-based interface
- ⚙️ **Server Support** — Vanilla, Fabric, and Forge servers with automatic JAR downloading
- ☕ **Java Management** — Automatic Java version detection and installation (Eclipse Temurin) per world
- ⌨️ **Script Generation** — Auto-generates start scripts for Windows (.bat) and Unix (.sh) with proper JVM flags
- 🤖 **Server Configuration** — Full control over RAM allocation, port, gamemode, difficulty, PVP, and more
- 🖥️ **Session Management** — Run servers in tmux sessions or foreground mode
- 📊 **Progress Tracking** — Real-time creation progress with stage indicators and scrollable logs
- 🎨 **Beautiful TUI** — Full-screen terminal interface powered by Bubble Tea with modern styling
## Installation
### From Source
```bash
# Clone the repository
git clone https://github.com/neuronexul/mcworker.git
cd mineworker-go
# Build
go build -o mcworker ./cmd/cli
# Run
./mcworker
```
### Requirements
- Go 1.25 or later
- Linux, macOS, or Windows
- tmux (optional, for background server sessions)
## Usage
Simply run the `mcworker` command to launch the interactive TUI:
```bash
mcworker
```
All functionality is driven through the TUI with proper interactive elements — no subcommands required.
### Keyboard Shortcuts
| Key | Action |
|-----|--------|
| `↑` / `k` | Navigate up |
| `↓` / `j` | Navigate down |
| `1-4` | Quick select menu item |
| `Enter` | Confirm selection |
| `Tab` | Next field (in forms) |
| `Shift+Tab` | Previous field (in forms) |
| `q` | Quit |
### Server Creation Workflow
When creating a new world, MineWorker automatically handles:
1. **Directory Setup** — Creates the world directory structure
2. **Java Runtime** — Downloads and installs the required Java version (if not present)
3. **Server Download** — Fetches the server JAR for your selected server type and version
4. **EULA Acceptance** — Automatically accepts the Minecraft EULA
5. **Script Generation** — Creates start scripts with optimized JVM arguments
6. **Configuration** — Saves the world configuration and generates `server.properties`
7. **Network Setup** — Configures port and DNS settings
## World Configuration
Each world is a self-contained unit with its own `worker.json` configuration:
```json
{
"world": {
"name": "my-survival-world",
"path": "./",
"minecraft_version": "1.21.11",
"description": "This is my survival forever world"
},
"server": {
"type": "fabric",
"jar": "fabric-server-1.21.11-0.18.4.jar",
"eula_accepted": true
},
"java": {
"version": "21",
"vendor": "temurin",
"path": "/home/neuronexul/.mcworker/java/temurin-21/bin/java"
},
"resources": {
"ram": {
"min": "2G",
"max": "4G"
},
"cpu": {}
},
"network": {
"port": 25565,
"dns": "mc.nexul.in"
},
"backups": {}
}
```
## Architecture
```
┌──────────────────────────────┐
│ Bubble Tea TUI │ ← Main menu, create world form, progress screen
└──────────────▲───────────────┘
│
┌──────────────┴───────────────┐
│ Application / Tasks │ ← Server creation orchestration
└──────────────▲───────────────┘
│
┌──────────────┴───────────────┐
│ Domain / Core Logic │ ← World, server types, validation
└──────────────▲───────────────┘
│
┌──────────────┴───────────────┐
│ Runtime / System Services │ ← Java, scripts, sessions, network
└──────────────────────────────┘
```
## Project Structure
```
mineworker-go/
├── cmd/cli/ # Entry point
├── internal/
│ ├── app/ # Application orchestration
│ │ └── create.go # Server creation workflow
│ ├── domain/ # Pure business logic
│ │ ├── server/ # Server type definitions
│ │ └── world/ # World configuration & validation
│ ├── network/ # Network configuration
│ ├── runtime/ # System integrations
│ │ ├── java/ # Java installation & management
│ │ ├── scripts/ # Start script generation
│ │ └── session/ # Process & session management
│ ├── servers/ # Server type implementations
│ │ ├── vanilla/ # Vanilla server support
│ │ ├── fabric/ # Fabric server support
│ │ └── forge/ # Forge server support
│ ├── tui/ # Bubble Tea UI components
│ │ ├── root.go # Root model & screen management
│ │ ├── main_menu.go # Main menu screen
│ │ ├── create_world.go # World creation form
│ │ ├── creation_progress.go # Progress tracking screen
│ │ └── styles.go # UI styles & theming
│ └── utils/ # Cross-platform utilities
│ └── paths.go # Path management
└── assets/ # Screenshots & media
```
## Supported Server Types
| Server Type | Description |
|------------|-------------|
| **Vanilla** | Official Minecraft server from Mojang |
| **Fabric** | Lightweight modding toolchain |
| **Forge** | Popular modding platform |
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Bubble Tea](https://github.com/charmbracelet/bubbletea) — TUI framework
- [Lip Gloss](https://github.com/charmbracelet/lipgloss) — Style definitions
- [Charm](https://charm.sh/) — For the amazing terminal tools ecosystem
- [Eclipse Temurin](https://adoptium.net/) — Java runtime distribution