mc-pack-builder-mcp

MCP server for Minecraft modpack building. Creates pack structures, searches mods on Modrinth, resolves dependencies, checks compatibility, and exports standardized modpacks ready for distribution.

Tools

Related MCP server: HMCL MCP Server

Features

• Pack structure creation — generates standard modpack directory with all required files

• Modrinth integration — search and query mod metadata directly from the Modrinth API

• Dependency resolution — follows the full dependency tree to ensure all requirements are met

• Compatibility checking — detects known conflicts (e.g. OptiFine with Fabric, Sodium vs Embeddium)

• Export standard pack — automatically cleans .minecraft extras, unwraps nested zip bundles, generates a styled modlist.html or plain modlist.txt, and optionally splits large packs into ≤256 MB volumes for easy distribution

• Offline operation — all local pack tools work without network; only search/info tools need Modrinth

Installation

Prerequisites

• Node.js 18+

• npm

Build

cd mc-pack-builder-mcp
npm install
npm run build

Run as standalone MCP server

node dist/index.js

The server communicates via stdio (JSON-RPC 2.0). It can be consumed by any MCP-compatible client.

Configuration for MCP clients

Add to your MCP client config:

{
  "mcpServers": {
    "mc-pack-builder": {
      "command": "node",
      "args": ["${MC_PACK_BUILDER_ROOT}/dist/index.js"]
    }
  }
}

Path note: Replace ${MC_PACK_BUILDER_ROOT} with the absolute path to this project's root directory. On Windows, use forward slashes: ["C:/Users/xxx/Desktop/mc-pack-builder-mcp/dist/index.js"]. Alternatively, set an environment variable MC_PACK_BUILDER_ROOT pointing to the project root and use the variable in the config.

Usage Examples

Create a new modpack

{
  "name": "create_pack",
  "arguments": {
    "pack_dir": "/path/to/MyModpack",
    "name": "My Modpack",
    "mc_version": "1.20.1",
    "loader": "fabric"
  }
}

Read pack info

{
  "name": "get_pack_info",
  "arguments": {
    "pack_dir": "/path/to/MyModpack"
  }
}

Search for a mod on Modrinth

{
  "name": "search_mods",
  "arguments": {
    "query": "sodium",
    "limit": 5
  }
}

Resolve dependencies

{
  "name": "resolve_dependencies",
  "arguments": {
    "project_id": "geckolib"
  }
}

Check pack compatibility

{
  "name": "check_pack_compatibility",
  "arguments": {
    "pack_dir": "/path/to/MyModpack",
    "mc_version": "1.20.1"
  }
}

Generate dependency list

{
  "name": "generate_dependency_list",
  "arguments": {
    "pack_dir": "/path/to/MyModpack"
  }
}

Export standard pack (release-ready)

{
  "name": "export_standard_pack",
  "arguments": {
    "source_pack_dir": "C:/Users/xxx/Desktop/MyModpack",
    "output_dir": null,
    "clean_minecraft_extra": true,
    "minecraft_dir": "C:/Users/xxx/.minecraft",
    "unwrap_nested": true,
    "generate_modlist": true,
    "modlist_format": "html",
    "split_volumes": false,
    "volume_max_mb": 256
  }
}

Output: Creates a _ready sibling directory (or custom output_dir) with the cleaned package. Returns a JSON report listing all actions taken, warnings, mod count, and — if volume splitting is enabled — per-volume paths and sizes.

Architecture

mc-pack-builder-mcp/
├── src/
│   └── index.ts        # MCP server + all tool implementations
├── dist/               # Compiled JavaScript (output of tsc)
├── __tests__/
│   └── unit.test.ts    # Unit tests (offline)
├── package.json        # Node.js dependencies (@modelcontextprotocol/sdk, zod, adm-zip)
├── tsconfig.json       # TypeScript config (CommonJS output)
├── test.js             # Integration test runner
├── test_logs/          # Test output logs (gitignored)
└── .gitignore

The MCP uses the official @modelcontextprotocol/sdk v1.x with McpServer and StdioServerTransport.

Testing

npm run build
node test.js

Tests create temporary directories under os.tmpdir() and clean up after themselves. No Minecraft installation is required.

Platform Compatibility

All tools use cross-platform Node.js fs and path APIs. Network-dependent tools (search_mods, get_mod_info, resolve_dependencies) require internet access regardless of platform.

License

MIT