mc-mod is a command-line tool for managing the mods and plugins of a Minecraft instance or server. Run it in the instance's folder and it opens a local web UI. The UI shows what's installed, searches Modrinth and CurseForge, and installs the right version for that instance's game version and loader, with its required dependencies.

Features

• Detects the instance. It reads the game version and loader from the files that launchers and servers already write, so you don't have to set them.
• Identifies installed jars by hash. It matches each file against Modrinth and CurseForge, and falls back to the jar's own metadata when there's no match. Jars built for the wrong loader or game version are flagged.
• Searches Modrinth and CurseForge, showing only results for your version and loader.
• Installs the best version, with its required dependencies, after you confirm the plan. Downloads are checked against the platform's hash before they're moved into mods/ or plugins/.
• Updates jars. "Check updates" finds the version it would install today for each identified jar, and you can update one, all of them, or switch a jar to any other version. The new file is downloaded and checked before the old one moves to .mc-mod/trash/.
• Exports server mods. It copies the mods a server needs (server-side and both-sides, plus those whose side nobody knows, for you to review) into server-mods/ or a zip, ready to upload. Client-only and disabled mods are left out, and your mods/ folder isn't changed.
• Shares the mod list. Share writes a JSON file with the game version, loader, loader version, Java version and every mod with its version. Import someone else's file and mc-mod picks versions that fit your instance, leaves out what you already have, and installs the ones you tick.
• Enables, disables and removes jars. Disabling renames the file to .jar.disabled. Removed jars go to .mc-mod/trash/ and aren't deleted: undo right away, or restore them later from Trash.
• Runs on your machine only. The server listens on 127.0.0.1 and needs a per-run session token. See Security.

Supported instances

| Kind | Detected from | |---|---| | Prism Launcher / MultiMC | mmc-pack.json | | CurseForge app | minecraftinstance.json | | Modrinth App | profile.json | | ATLauncher | instance.json | | Vanilla launcher, TLauncher | versions/<id>/<id>.json, launcher_profiles.json | | Fabric, Quilt, Forge and NeoForge servers | launcher jars, libraries/, run.sh | | Paper, Purpur, Spigot, Bukkit and Folia servers | paper-global.yml, purpur.yml, spigot.yml, … | | Velocity, BungeeCord and Waterfall proxies | velocity.toml, BungeeCord config.yml |

If none of these match, it guesses from the jars in mods/. If it still can't tell, the UI asks you for the version and loader and remembers the answer. Details are in artifacts/instance-detection.md.

Requirements

• Bun 1.3 or newer
• A browser. A Chromium-based browser (Chrome, Edge, Brave, Chromium) opens the UI in its own window.

Install

With Bun 1.3 or newer:

bun add -g mc-mod

Or run it once without installing: bunx mc-mod.

Standalone binary

If you don't have Bun, download the binary for your platform from the latest release. It has the runtime built in, so it needs nothing else.

| Platform | File | |---|---| | Linux x64 | mc-mod-linux-x64 | | Linux arm64 | mc-mod-linux-arm64 | | macOS Apple silicon | mc-mod-darwin-arm64 | | macOS Intel | mc-mod-darwin-x64 | | Windows x64 | mc-mod-windows-x64.exe |

On Linux and macOS, rename it to mc-mod, make it executable and move it onto your PATH:

chmod +x mc-mod-linux-x64
sudo mv mc-mod-linux-x64 /usr/local/bin/mc-mod

macOS blocks binaries downloaded in a browser. Clear the flag once with xattr -d com.apple.quarantine mc-mod. Each release lists SHA-256 checksums in SHA256SUMS.

Updating

bun update -g mc-mod, or download the new binary. The instance state in .mc-mod/ and your settings carry over.

From source

git clone https://github.com/nexuls/mc-mods-manager.git
cd mc-mods-manager
bun install
bun run build
cd apps/cli && bun link

Usage

Go to the instance or server folder and run mc-mod:

cd ~/.local/share/PrismLauncher/instances/MyPack
mc-mod

It prints what it detected and opens the UI. Press Ctrl+C to stop it.

You can also point it at a folder, or start it from inside mods/ or plugins/:

mc-mod -d ~/servers/survival

Options

| Option | Description | |---|---| | -d, --dir <path> | Instance directory to manage. Default: $MC_MOD_DIR, then the current directory. | | -p, --port <port> | Port to listen on. Default: 4719, or a free port if that one is taken. | | --no-open | Don't open a browser. Just print the URL. | | -b, --browser <mode> | auto (default) uses an app window if a Chromium browser is found and a tab otherwise. app always uses an app window, tab always uses a tab. | | --exit-on-close | Stop the server about a minute after the UI is closed. | | -v, --version | Print the version. | | -h, --help | Show help. |

On a remote server

Run it without opening a browser and forward the port over SSH:

# on the server
mc-mod --no-open -p 4719

# on your computer
ssh -L 4719:127.0.0.1:4719 you@server

Then open the URL that mc-mod printed, including its ?t= token, in your local browser.

CurseForge

Modrinth works without any setup. CurseForge's API needs a key:

1. Create a key in the CurseForge developer console.
2. Paste it in Settings in the UI. You can test it there too.

You can also set the CURSEFORGE_API_KEY environment variable, which takes priority over the saved key. The key is only used by the local server. It's never sent to the browser.

Without a key, CurseForge mods installed by the CurseForge app, Prism or ATLauncher are still recognized from those launchers' own records.

Some CurseForge authors don't allow third-party downloads. For those files, the UI shows a Download link to the file's page. Once you've put the jar in mods/, mc-mod identifies it.

Files it writes

| Path | Contents | |---|---| | <instance>/.mc-mod/state.json | Version and loader overrides, links you set by hand, and a hash cache. Safe to delete: jars are identified again by hash. | | <instance>/.mc-mod/tmp/ | Downloads that haven't been verified yet | | <instance>/.mc-mod/trash/ | Removed jars and ones replaced by updates, until you empty the trash | | <instance>/server-mods/ or <instance>/server-mods-<version>-<date>.zip | Server exports, when you make one (folder name set in Settings). A new folder export replaces the jars of the last one. | | ~/.config/mc-mod/config.json | Global settings and the CurseForge key, readable only by you (%APPDATA%\mc-mod\Config\ on Windows, ~/Library/Preferences/mc-mod/ on macOS) |

It changes nothing else in the instance except the jars in mods/ or plugins/, and the export you ask for.

How it works

mc-mod is both the command and the server. It works out the instance's game version and loader, then serves the web UI and a JSON API on 127.0.0.1. The API is what reads your jars, talks to Modrinth and CurseForge, and writes files. The browser only talks to that local server. The design is in artifacts/architecture.md.

Security

The server listens only on 127.0.0.1. It rejects requests that don't carry the session token for that run, and requests with an unexpected Host header. File changes stay inside the instance directory. Downloads come only from Modrinth's and CurseForge's CDNs over HTTPS, and are checked against the platform's hash.

To report a vulnerability, see SECURITY.md.

Roadmap

• [x] Instance detection
• [x] Installed mods: identify, enable/disable, remove
• [x] Search and install from Modrinth
• [x] CurseForge search, installs and identification
• [x] Update checks, and updating one mod or all of them
• [x] Server export: copy the server-side mods to a folder or a zip for upload
• [x] Share the mod list as a file, and import someone else's
• [x] Published to npm as mc-mod, with standalone binaries on GitHub releases

Progress is tracked in artifacts/progress.md.

Development

The repository is a Bun workspace:

apps/web         Vite + React + Tailwind + shadcn/ui (the UI)
apps/cli         Express server and the mc-mod command
packages/shared  zod schemas and the API contract, shared by both
artifacts/       design docs, specs, decisions and progress

bun install
cp apps/cli/.env.example apps/cli/.env.local   # set MC_MOD_DIR to a test instance
bun run dev          # CLI on :4719 and Vite on :5173, in a tmux session
bun run dev --kill   # stop it
bun run check        # Biome lint and format check
bun run typecheck
bun test
bun run build        # npm package in apps/cli
bun run compile      # standalone binary in dist/release/

Releases are cut by hand from GitHub Actions. See artifacts/releasing.md.

Use a copy of an instance for MC_MOD_DIR, not the one you play on.

Bun is the only package manager, runtime and test runner. Read AGENTS.md before you contribute. It covers the conventions, the safety rules and the commit style. The design is in artifacts/architecture.md.

License

MIT

mc-mod isn't affiliated with Mojang, Microsoft, Modrinth or CurseForge.