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