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

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.

Configuration

本工具零配置即可用（内置默认值，任何环境开箱即用）。以下项目可通过环境变量或项目根目录 .env 文件覆盖（复制 .env.example 为 .env）：

优先级：环境变量 > .env 文件 > 内置默认值。改动后重启 MCP server 生效。

扩展兼容性规则：编辑 src/pack-rules.json（构建后为 dist/pack-rules.json），新增/覆盖规则即可，无需改代码。

• rules.incompatible_pairs：互斥模组对，如 { "mods": ["sodium", "embeddium"], "reason": "..." }，当同一整合包同时出现 ≥2 个名单内模组时告警。

• rules.loader_incompatible：加载器专属不兼容，如 { "loader": "fabric", "mods": ["optifine"], "reason": "..." }。

• rules.pack_format：MC 版本 → pack.mcmeta 的 pack_format 数字映射（create_pack 默认取值）。

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
│   └── pack-rules.json # 兼容性规则 & pack_format 映射（可外部扩展）
├── 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)
├── .env.example        # 环境变量配置示例
└── .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