# Minecraft Mods MCP

A local [MCP](https://modelcontextprotocol.io) 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](https://nodejs.org/) 20 or newer
- [CurseForge App](https://www.curseforge.com/download/app) with at least one Minecraft instance
- [Cursor](https://cursor.com/) (or another MCP client)

## Install (recommended)

```bash
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](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**

```json
{
  "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**

```json
{
  "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:

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

| 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

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`):

```bash
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](.env.example) to `.env` and set your Instances path, then:

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

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

**Cursor config** (after `docker compose create`):

```json
{
  "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:

```bash
docker compose build
```