minecraft-mod-mcp-server

Cloudflare Workers MCP server for Minecraft modpack development. Generates FTB Quests chapters and tasks, KubeJS scripts (weapons, armor, recipes), validates SNBT/config files, and provides diagnostic checks.

Deployment Status

Deployed at: https://minecraft-mcp.mcjj.workers.dev

This project runs as a Cloudflare Worker and is live at the URL above. For local development and testing, see Local Development below.

Local Development

Run locally to preview and test before deploying:

http://localhost:8788/mcp

Tools

FTB Quests Generation

| Tool | Description | |------|-------------| | generate_quest_chapter | Generate a complete FTB Quests chapter file (SNBT format) with multiple tasks, dependencies, and rewards | | generate_quest_task | Generate a single FTB Quests task definition (item/kill/advancement/checklist types) | | generate_hex_id | Generate a 16-bit random hex ID for FTB Quests chapter/task IDs | | generate_chapter_group_snbt | Generate chapter_groups.snbt to define quest book grouping (main/branch quests) | | generate_quest_data_snbt | Generate data.snbt quest book main config (title, icon, progress mode) |

KubeJS Script Generation

| Tool | Description | |------|-------------| | generate_kubejs_weapon | Generate KubeJS weapon registration code (attack damage, speed, durability, skills) | | generate_kubejs_armor_set | Generate KubeJS armor set registration code (helm/chest/leggings/boots with tier definitions) | | generate_kubejs_shaped_recipe | Generate KubeJS shaped recipe code (3x3 crafting pattern with ingredient mapping) | | generate_kubejs_shapeless_recipe | Generate KubeJS shapeless recipe code (just ingredients and output) | | generate_kubejs_smelting | Generate KubeJS smelting/furnace/smoker recipe code | | generate_kubejs_remove_recipe | Generate KubeJS recipe removal code (override or disable vanilla/mod recipes) |

Validation & Diagnostics

| Tool | Description | |------|-------------| | validate_snbt | Validate SNBT file syntax (check unmatched braces, Count format issues, etc.) | | check_kubejs_errors | Check KubeJS scripts for common errors (deprecated APIs, Rhino engine compatibility issues) | | generate_item_texture_path | Generate KubeJS item/armor texture path guide for correct file placement |

Features

• FTB Quests generation — full SNBT output for quest books with dependencies, rewards, and grouping
• KubeJS script generation — weapons, armor, shaped/shapeless/smelting recipes, and recipe removals
• SNBT validation — catches syntax errors before they cause runtime issues in-game
• KubeJS diagnostics — detects deprecated APIs and Rhino engine compatibility problems
• Zero network dependency — all generation is purely algorithmic; no external APIs called
• Cloudflare Workers ready — designed for edge deployment; no network or external API dependency for generation logic

Installation (Local Development)

Prerequisites

• Node.js 18+
• npm
• Wrangler CLI

Setup

cd minecraft-mcp-server
npm install

Run locally

npm start
# or
npx wrangler dev

Then connect via MCP client to http://localhost:8788/mcp.

Deploy to Cloudflare

npm run deploy

Configuration for MCP clients

Local development — connect to the local server:

{
  "mcpServers": {
    "minecraft-mod": {
      "url": "http://localhost:8788/mcp"
    }
  }
}

Production deployment — connect to the live endpoint:

{
  "mcpServers": {
    "minecraft-mod": {
      "url": "https://minecraft-mcp.mcjj.workers.dev/mcp"
    }
  }
}

Architecture

minecraft-mcp-server/
├── src/
│   ├── index.ts           # Cloudflare Worker entry point + MCP server setup
│   ├── types.ts           # Cloudflare Workers environment types
│   ├── tools/
│   │   ├── quest.ts       # FTB Quests generation logic
│   │   ├── kubejs.ts      # KubeJS script generation logic
│   │   └── validate.ts    # SNBT validation + KubeJS diagnostics
│   └── templates/
│       ├── quest_chapter.ts
│       ├── kubejs_item.ts
│       └── kubejs_recipe.ts
├── __tests__/
│   └── unit.test.ts       # Unit tests (fully offline, 49 tests)
├── vitest.config.ts       # Vitest config (ESM, globals: false)
├── package.json           # Dependencies (@modelcontextprotocol/sdk, agents, zod, wrangler)
└── wrangler.jsonc         # Cloudflare Workers deployment config

The MCP server is built on the @modelcontextprotocol/sdk v1.x and is designed to run as a Cloudflare Worker via the agents library's createLegacyMcpHandler.

Testing

npm test
# or
npx vitest run

All 49 unit tests run fully offline — no network or Cloudflare account required for testing.

Platform Compatibility

| Aspect | Windows | macOS | Linux | |--------|---------|-------|-------| | Local dev (wrangler dev) | ✅ | ✅ | ✅ | | Unit tests (vitest) | ✅ | ✅ | ✅ | | Production deployment | Requires Cloudflare account | Requires Cloudflare account | Requires Cloudflare account |

This project is designed to run on Cloudflare Workers. For local development and testing, use wrangler dev — no Cloudflare account or internet connection is required. The generation logic is pure TypeScript and fully offline. To deploy to production, you need a Cloudflare account with Workers enabled.

License

MIT

Security Notes

npm audit --omit=dev reports 0 vulnerabilities. The MCP protocol packages are pinned to patched versions via overrides in package.json (@modelcontextprotocol/sdk ^1.32.1, @modelcontextprotocol/client ^2.3.1, @modelcontextprotocol/server ^2.3.1), because the agents library pins older vulnerable versions and upgrading it to a fixed major release would be a breaking change. All 14 tools declare the four MCP annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint) and a zod inputSchema.