How do I use mc-mod-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mc-mod-mcp Show me a @ModifyVariable mixin example" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mc-mod-mcp

An MCP server that gives Claude grounded answers when you're writing Minecraft mods.

It targets the two eras of the modding scene that are actually still alive — 1.8.9 (Forge/MCP, Java 8, Hypixel-style client mods) and 1.21.10+ (NeoForge or Fabric, Java 21, Mojang-mapped, Data Components). For 1.21.x it can also do live mapping lookups against linkie and pull mappings straight from piston-meta when linkie hasn't ingested a fresh release yet.

Without this, Claude tends to mix the two eras, hallucinate new ResourceLocation(...) (gone since 1.20.5), forget that items use Data Components instead of NBT, and write ServerboundUseItemPacket without the new sequence/yaw/pitch fields. With it, the model has a fact to look up instead of a name to guess.

Install

git clone https://github.com/ratph6/mc-mod-mcp
cd mc-mod-mcp
npm install
npm run build

Then point Claude Code at the built binary:

claude mcp add mc-mod node "$PWD/dist/index.js"

(or hand-edit ~/.claude/config.json if you prefer).

Usage

Just ask in plain English. Claude picks the tool. Some examples that actually exercise it:

How do I send a useItem packet in 1.21.10 Fabric?
Translate this 1.8.9 snippet to 1.21+: Minecraft.getMinecraft().thePlayer.addChatMessage(new ChatComponentText("hi"))
Scaffold a NeoForge 1.21.10 mod main class for examplemod
Show me a @ModifyVariable mixin example
What's the Yarn name for LocalPlayer in 1.21.10?

Tools

name	what it does
`mc_version_info`	Loaders, Java, mappings, build system, doc links for an era
`mc_lookup_class`	Fully-qualified class name in 1.8.9 vs 1.21+ for a concept (`Block`, `Level`, `BlockEntity`, …)
`mc_lookup_api`	Canonical snippet for a task (`send chat`, `open gui`, `register block`, …)
`mc_translate`	Given a symbol from one era, suggest the equivalent in the other
`mc_event`	"What event fires when X?" — gives 1.8.9 + NeoForge + Fabric
`mc_mixin`	Mixin pattern catalog (`@Inject`, `@ModifyArg`, `@WrapOperation`, `@Accessor`, …) plus mixin config JSON
`mc_gotchas`	Era-specific pitfalls — Data Components, ResourceLocation factory, mod bus vs game bus, etc. Filterable.
`mc_gradle`	`build.gradle` / `settings.gradle` / `gradle.properties` for an era + loader
`mc_mappings_translate`	Yarn ↔ Mojang class name translation (curated)
`mc_list_scaffolds`	Enumerate scaffold templates
`mc_scaffold`	Emit boilerplate (mod main, item/block, command, key binding, mixin, network payload, …)
`mc_docs`	Doc links for an era
`mc_list_versions`	Live: every version linkie knows, per namespace
`mc_mappings_search`	Live: full-text search against linkie's mappings API
`mc_lookup_field`	Live: field-name lookup against linkie (the curated tables don't track fields)
`mc_mojang_mappings`	Pulls Mojang's `client_mappings.txt` directly via piston-meta. Used for 26.1.x and any version linkie chokes on.

The first twelve are curated — fast, deterministic, no network. The last four hit the network on demand.

Extending

Knowledge lives in src/knowledge.ts as flat data. Add an entry to CLASSES / METHODS / EVENTS / MIXIN_PATTERNS / GOTCHAS / YARN_TO_MOJANG / GRADLE_TEMPLATES, run npm test, done. Scaffolds are template functions in the same file, listed via SCAFFOLD_KINDS.

src/
  index.ts          MCP server, tool definitions, stdio transport
  knowledge.ts      Curated data + scaffold templates
  linkie.ts         Live calls to linkie's mappings API
  mojang.ts         Live piston-meta + proguard parser
  smoke.test.ts     node:test smoke tests

Caveats

It doesn't ship Mojang/Yarn/Parchment mapping files (multi-MB) — for raw obf names use the live tools or linkie. It won't tell you whether your specific code compiles, only that the API shape is right for the era. Translations target 1.8.9 and 1.21.10; intermediate versions usually still apply but treat them as approximate.