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.

Related MCP server: mc-host

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:

Configuration

Resolution order for the instances folder:

1. CURSEFORGE_INSTANCES_DIR environment variable

2. curseforgeInstancesDir in mcp.config.json (next to this README)

3. ~/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

What to say in chat

1. New computer: “Run a system check” / “Is this MCP set up on this PC?”

2. Use a pack: “Use the ATM10 instance.”

3. Make a world with fewer mods: “Create a world called LiteSky with about 80 mods, keep Create and Mekanism, drop Twilight Forest.”

4. Change that world’s mods: “On LiteSky, disable the Aether and enable JEI.”

5. Apply before launch: “Apply the LiteSky world profile.” Then launch that CurseForge instance and open/create a world named LiteSky.

6. Configs: “In mekanism-common.toml set this ore setting to X and reset LiteSky.”

7. 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