Minecraft Mods MCP

A local MCP server that lets Cursor (or any MCP client) talk to CurseForge Minecraft instances on your machine.

It can create a world profile inside a pack, pick which mods belong to that world, edit configs, diagnose crashes, and reset a world so the next launch uses those changes.

Java mods load when the game starts, not when you click a world. This server stores a profile per world and applies it to the instance on disk before you launch.

What it does

List and select CurseForge instances
Read-only system check on a new computer (health_check)
List, compare, and recommend mods (keeps required dependencies)
Create world profiles (which mods are on/off for a named world)
Apply a profile on disk before launch (enable/disable jars, patch configs)
Read and edit config files
Parse crash logs and disable likely culprits after a backup
Register a dedicated server folder for compare/diagnose

Profiles live in <instance>/.mcp/worlds/. World backups go to <instance>/.mcp/backups/. Session state (current instance, extra server paths) lives in ~/.minecraft-mcp/state.json.

Requirements

Node.js 20 or newer
CurseForge App with at least one Minecraft instance
Cursor (or another MCP client)

Install (recommended)

git clone https://github.com/bmidd0170-sys/Minecraft-MCP-.git
cd Minecraft-MCP-
npm install
npm run build
npm run self-test

self-test (and the health_check tool) are read-only. They check Node, the Instances folder, that packs are readable, and whether logs exist. They do not apply profiles or change jars. If the Instances folder is missing, set CURSEFORGE_INSTANCES_DIR (see below).

On a new device, ask Cursor: “Run a system check” (it should call health_check first).

Copy mcp.config.example.json to mcp.config.json only if you want a file-based override. The env var is enough for most people.

Cursor config

Add a server to your MCP config (user-level Cursor settings, or this project’s .cursor/mcp.json). Use your paths, then reload MCP / restart Cursor.

Windows

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["C:\\path\\to\\minecraft-mcp\\dist\\index.js"],
      "env": {
        "CURSEFORGE_INSTANCES_DIR": "C:\\Users\\YOURNAME\\curseforge\\minecraft\\Instances"
      }
    }
  }
}

macOS / Linux

{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": ["/path/to/minecraft-mcp/dist/index.js"],
      "env": {
        "CURSEFORGE_INSTANCES_DIR": "/Users/YOURNAME/curseforge/minecraft/Instances"
      }
    }
  }
}

Typical CurseForge instances folders:

OS	Default path
Windows	`%USERPROFILE%\curseforge\minecraft\Instances`
macOS	`~/curseforge/minecraft/Instances`
Linux	`~/curseforge/minecraft/Instances`

Configuration

Resolution order for the instances folder:

CURSEFORGE_INSTANCES_DIR environment variable
curseforgeInstancesDir in mcp.config.json (next to this README)
~/curseforge/minecraft/Instances

Optional extra Minecraft server folders:

SERVER_PATHS — delimiter-separated absolute paths (: on macOS/Linux, ; on Windows)
serverPaths in mcp.config.json
register_server at runtime (persisted in ~/.minecraft-mcp/state.json)

Tools

Tool	Purpose
`health_check`	Read-only setup check on a new computer
`list_instances` / `get_instance` / `use_instance`	Find and select a CurseForge pack
`register_server`	Remember a dedicated server folder
`list_mods` / `analyze_mods` / `compare_mods` / `recommend_mods`	Inspect and slim a mod list
`list_worlds` / `create_world` / `set_world_mods` / `apply_world` / `reset_world`	World profiles
`list_configs` / `read_config` / `edit_config`	Config files
`list_logs` / `read_log` / `diagnose` / `apply_fix`	Crashes and safe disable

What to say in chat

New computer: “Run a system check” / “Is this MCP set up on this PC?”
Use a pack: “Use the ATM10 instance.”
Make a world with fewer mods: “Create a world called LiteSky with about 80 mods, keep Create and Mekanism, drop Twilight Forest.”
Change that world’s mods: “On LiteSky, disable the Aether and enable JEI.”
Apply before launch: “Apply the LiteSky world profile.” Then launch that CurseForge instance and open/create a world named LiteSky.
Configs: “In mekanism-common.toml set this ore setting to X and reset LiteSky.”
Crashes: “Diagnose ATM10” then “Apply the fix on LiteSky.”

Switching worlds that use different mod lists: apply the other profile, then relaunch the game.

What it will not do

Log into CurseForge
Download new mods (install those in the CurseForge app, then they show up here)
Delete .jar files (it only renames them to .jar.disabled)
Generate terrain offline (you create/open the world in Minecraft once)

Optional: Docker

This server speaks stdio and must read/write your instance folders. Docker is optional. Node (above) is the simpler install.

Published image (built on every push to main):

docker pull ghcr.io/bmidd0170-sys/minecraft-mcp:latest

If pull is denied, the GitHub Package may still be private: on GitHub open Packages for this repo, then set minecraft-mcp to public.

The image runs in a dedicated container named Minecraft-MCP (Docker names cannot contain spaces). Copy .env.example to .env and set your Instances path, then:

docker compose create

That creates the container without starting it. Cursor attaches with docker start -ai Minecraft-MCP. When Cursor disconnects, the container stops but stays in Docker Desktop under that name.

docker compose create
docker compose run --rm minecraft-mcp --self-test

Cursor config (after docker compose create):

{
  "mcpServers": {
    "minecraft": {
      "command": "docker",
      "args": ["start", "-ai", "Minecraft-MCP"]
    }
  }
}

-i / -a are required (stdio). The instances mount must be writable.

To build locally instead of pulling:

docker compose build