mcreator-mcp

mcreator-mcp is an independent integration that lets MCP clients inspect and operate an open MCreator workspace through MCreator's own Java APIs.

The project has two parts:

• plugin/mcreator-mcp-plugin: a Java plugin running inside MCreator. It owns all workspace, element, generator, resource, and build operations.
• packages/mcreator-mcp-server: a TypeScript MCP server that discovers the local plugin bridge, validates MCP inputs, and translates requests into the versioned bridge protocol.

The MCP process never edits .mcreator or .mod.json files. Element persistence and workspace saves are performed inside MCreator through ModElementManager, Generator, and WorkspaceFileManager.

Current compatibility target

• MCreator 2026.2 source revision 60116f9cdfee30bad359bffa0138736daac389d6
• Bridge API 0.1.0
• MCP TypeScript SDK v2
• MCP protocol 2026-07-28
• Node.js 20 or newer
• Java 25 for plugin compilation against MCreator 2026.2

See docs/mcreator-source-map.md before changing any adapter workflow.

Development

The audited MCreator checkout is intentionally ignored at .upstream/MCreator.

git clone --recursive https://github.com/MCreator/MCreator.git .upstream/MCreator
pnpm install
pnpm build
pnpm test

Plugin compilation requires compiled MCreator 2026.2 classes or a matching MCreator JAR. The canonical Windows build uses MCreator's pinned JBR toolchain:

.upstream\MCreator\gradlew.bat -p .upstream\MCreator downloadJDKWin64
$env:JAVA_HOME=(Resolve-Path '.upstream\MCreator\jdk\jbr25_win_64').Path
.upstream\MCreator\gradlew.bat -p .upstream\MCreator classes
.upstream\MCreator\gradlew.bat -p plugin\mcreator-mcp-plugin `
  -PmcreatorHome="$((Resolve-Path '.upstream\MCreator').Path)" clean test jar

Copy plugin/mcreator-mcp-plugin/build/libs/mcreator-mcp-plugin-0.1.0.jar into MCreator's user plugins directory, enable Java plugins in MCreator preferences, and restart MCreator. Then build and configure the stdio server command:

pnpm build
node packages/mcreator-mcp-server/dist/index.js

MCreator Java plugins are disabled by default. The bridge does not exist until that preference is enabled and MCreator is restarted.

Security

The Java bridge binds only to 127.0.0.1, chooses a dynamic port by default, and requires a random bearer token on every request. Its discovery file is created under the current user's profile with owner-only permissions where supported. Set MCREATOR_MCP_READ_ONLY=true before starting MCreator to reject all mutation, generation, build, and run operations.

This project does not expose arbitrary shell commands, arbitrary Gradle tasks, arbitrary filesystem reads, or arbitrary filesystem writes.

Resource imports accept bounded base64 payloads. Generated-source reads and application-log diagnostics are confined to MCreator-known files.

License and trademark

Licensed under GPL-3.0-or-later. MCreator is a trademark of Pylo. This is an independent, unofficial integration and is not endorsed by or affiliated with Pylo or the MCreator project.