# 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](docs/mcreator-source-map.md) before changing any adapter workflow.

## Development

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

```powershell
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:

```powershell
.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:

```powershell
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.