🛠️ ModHelper-MCP

Unified Super-Server for Minecraft Modding & In-Game Automation

ModHelper-MCP is an all-in-one Model Context Protocol (MCP) server providing 81 tools across modding platforms, documentation search, project scaffolding, SQLite modding knowledge engines, and live MineFlayer in-game bot automation.

---

🚀 Features & Tool Groups (81 Tools Total)

All tools are organized into 9 logical groups. Activate the groups you need via MODHELPER_MCP_ENABLED_TOOLS in your mcp_config.json.

Group	Tools	Description
modrinth	10	Search Modrinth projects, versions, download files, check updates, resolve dependencies.
curseforge	9	Search CurseForge mods, files, download links, resolve full dependency trees.
nexus	7	Validate API keys, search games, fetch mod files, resolve official CDN download links.
thunderstore	5	Search communities, browse package manifests, download zip bundles.
steam	4	Search Steam Workshop items, fetch details, resolve download URLs.
git	2	Clone external reference mods, download official MDK templates (NeoForge/Forge/Fabric).
docs	3	Sync platform documentation, full-text search reference code and documentation files.
dev	4	Bootstrap dev servers, launch dev clients, refactor template packages, cleanup caches.
knowledge	15	Explain modding concepts, search docs (FTS), Parchment mappings (class/method/field/obf lookup), search canonical mod examples (Create, Botania, AE2).
automation	25	Live MineFlayer in-game bot control: movement, pathfinding, digging, placing, inventory, containers, crafting, trading, entity interaction.

---

⚙️ IDE Configuration (mcp_config.json)

All tools are disabled by default. Set MODHELPER_MCP_ENABLED_TOOLS to activate the groups you need.

Option A: Via npx (Recommended)

{
  "mcpServers": {
    "modhelper-mcp": {
      "command": "npx",
      "args": ["-y", "@britakee/modhelper-mcp"],
      "env": {
        "CURSEFORGE_API_KEY": "YOUR_CURSEFORGE_API_KEY",
        "MODRINTH_API_KEY": "YOUR_MODRINTH_API_KEY",
        "MODHELPER_MCP_ENABLED_TOOLS": "modrinth,curseforge,knowledge,automation,dev,docs,git"
      }
    }
  }
}

Option B: Local Python Module

{
  "mcpServers": {
    "modhelper-mcp": {
      "command": "python",
      "args": ["-m", "modhelper_mcp.server"],
      "cwd": "C:\\path\\to\\minecraft-mcp",
      "env": {
        "CURSEFORGE_API_KEY": "YOUR_CURSEFORGE_API_KEY",
        "MODRINTH_API_KEY": "YOUR_MODRINTH_API_KEY",
        "MODHELPER_MCP_ENABLED_TOOLS": "modrinth,curseforge,knowledge,automation"
      }
    }
  }
}

---

🔑 Environment Variables & Group Options

Variable	Description
MODHELPER_MCP_ENABLED_TOOLS	Comma-separated active groups: modrinth,curseforge,nexus,thunderstore,steam,git,docs,dev,knowledge,automation
MODHELPER_MCP_DISABLED_TOOLS	Optional: remove specific individual tools from an enabled group
CURSEFORGE_API_KEY	Official CurseForge API token (x-api-key)
MODRINTH_API_KEY	Optional Modrinth API token (increases rate limits)
NEXUS_API_KEY	Optional Nexus Mods API Key
STEAM_API_KEY	Optional Steam Web API Key
MCMODDING_DATA_DIR	Custom path to mcmodding SQLite databases (default: ./data/mcmodding)

---

🤖 Protocol Safety for In-Game Bot Automation

When using bot_connect, specify minecraft_version to pin the exact protocol version:

• Pass "1.20.1" when connecting to a Forge / Fabric 1.20.1 server.
• Pass "1.21.1" when connecting to a NeoForge / Fabric 1.21.1 server.

This enforces correct MineFlayer packet serialization and registry loading, avoiding protocol desync errors on multi-version test servers.

---

📦 Installation & Setup

1. Python dependencies: Python 3.10+

   pip install -e .

2. In-game automation dependencies (optional): Node.js 18+

   npm install mineflayer mineflayer-pathfinder vec3

---

📄 License & Credits

• Created by Britakee (Britakee Studios)
• Distributed under the MIT License.