MixinMCP

Extends IntelliJ's built-in MCP Server with tools for Minecraft mod development, with the goal of improving mixin writing and inter-mod compatibility.

GitHub: https://github.com/muon-rw/MixinMCP

For all features, you will also need the Gradle plugin - see https://github.com/muon-rw/MixinMCP#Setup

Key features:

1. Broad-scoped search:

• Full type hierarchy: supertypes, subtypes, and all implementations of an interface or abstract class
• Find all overrides of a method, plus its original super-method declaration
• Call hierarchy: callers and callees of any method
• All references to a class, method, or field
• All @Mixin classes targeting a given class method. Helps identify cross-mod conflicts
• Symbol search by name pattern, plus regex grep across all dependency sources

Regex search across your entire classpath including dependencies:

• Alternative tools have a central problem: You can not perform broad, text-based search like regex on files that aren't in your project's own source. This is exactly the use case that Minecraft development (and mixin writing) needs so desparately - 100 other projects might be interacting with what you are, and you need to know what and how. While other tools might be able to read individual files in Minecraft sources, loader or mod APIs, libraries, or other mods you've added for integration or compatibility, they don't have a good way to search through them.
• With this plugin, agents can easily scan the whole project dependency network on their own, including dependencies without published sources.
• Circumvents the need to manually copy and paste snippets into context, or for agents to find jars in your gradle cache and unzip/analyze them manually one by one.

2. Class/Method Bytecode lookup:

• Get the actual compiled bytecode for a given class or method
• Useful to find a precise target when writing mixins, especially for ordinals or synthetic lambdas

3. Built-in Agent Skills for enhanced Mixin Writing:

• Improve compatibility of written mixins by favoring MixinExtras injectors which LLMs often hallucinate or fail to use in the first place
• Favor precise modification for the exact target for the task without workarounds, slices, or shift by's, thanks to MixinExtras' robust @Expression annotation

4. Automatic Mappings lookup:

• Easily convert any class, method, or field name between SRG, Intermediary, Yarn, Mojmap, and obf
• Mappings are downloaded on demand (Mojang launcher meta, Fabric Maven, Forge/NeoForge Maven) and cached under ~/.cache/mixinmcp/mappings/
• This allows you to retrieve mapping data for (almost) any version or loader, even those not present in the current project

Setup

MixinMCP has two parts. You need both for full-classpath search to work:

• IntelliJ plugin: registers the mixin_* tools on IntelliJ's built-in MCP Server.
• Gradle plugin: decompiles dependencies that don't publish sources so the search tools cover every JAR on your classpath.

Prerequisites: IntelliJ IDEA 2025.3+

1. Install the IntelliJ plugin

From IntelliJ: Settings → Plugins → Marketplace → search "MixinMCP" → Install

2. Enable IntelliJ's MCP Server

• Settings → Plugins → search "MCP Server" and confirm it's enabled. (Bundled by default on recent IntelliJ versions.)
• Settings → Tools → MCP Server → check Enable MCP Server.

3. Connect your MCP client

Use IntelliJ's Auto-Configure option for your client (or configure manually using the ip address), then restart the client. The auto-configured server name is usually user-jetbrains

[!CAUTION] MixinMCP exposes full project and dependency source, classpath metadata, and bytecode to whatever connects to the MCP server. These tools aren't hardened for remote access. IntelliJ binds the server to localhost by default — leave it that way unless you have a specific reason, and expose it more broadly at your own risk.

For adherence and other optimizations, see Bundled Rules and Skills.

4. Set up the Gradle plugin

[!IMPORTANT] Without this step, mixin_search_in_deps and mixin_get_dep_source can only see dependencies that published a -sources.jar. This means that local jar dependencies, Cursemaven dependencies, and many from Modrinth Maven dependencies are totally invisible. The Gradle plugin decompiles these via Vineflower into a local cache that the IntelliJ plugin indexes automatically.

1. Add the MixinMCP maven repository to your mod project's settings.gradle or settings.gradle.kts:

// .kts format
pluginManagement {
    repositories {
        maven { url = uri("https://maven.muon.rip/releases") }
        gradlePluginPortal()
        // ... your existing repos (maven, fabricmc, neoforged, etc.)
    }
}

2. Apply the plugin in your mod project's build.gradle or build.gradle.kts:

plugins {
    // ... your existing plugins ...
    id("dev.mixinmcp.decompile") version "0.9.0"
}

3. Increase Gradle process memory: (Strongly Recommended)

[!CAUTION] If you skip this step, you might experience OOM errors during gradle sync

Add to your project level gradle.properties:

org.gradle.jvmargs=-Xmx4g
# You may need to set this as high as 6g if you need 
# to decompile an extremely large jar (e.g. Cataclysm)

[!WARNING] Setting org.gradle.parallel=true (default for Neoforge template) can increase likelihood of OOMs during big decomps

For more info, see Decompilation cache details

4. Run decompilation:

./gradlew genDependencySources

(This task already runs automatically after every gradle sync, but it can sometimes need to rerun manually)

The IntelliJ plugin reads the dependency sources cache on project open and after every Gradle sync/task run.

MixinMCP warns on project open when the Gradle plugin is missing. If you don't need full-classpath decompilation and want to silence this, disable Warn when Gradle plugin is not detected in Settings → Tools → MixinMCP.

For local development against an unpublished build, see Decompilation cache details below.

5. Verify

Ask the model to list MCP tools from the JetBrains server. The mixin_* tools should appear. If they don't: (1) confirm MixinMCP is installed, (2) confirm the MCP Server plugin is enabled, (3) confirm your client is connected (most common failure)

Bundled Rules and Skills

On project open for Minecraft mod projects (Fabric, Forge, NeoForge, Quilt, Architectury), MixinMCP copies bundled assistant files: Cursor rules and skills under .cursor/, and Claude Code skills under .claude/skills/.

These provide better context for the LLM about why they should use these tools, and when and how to use each tool, common pitfalls, and a mixin workflow checklist.

Injected files are automatically added to .gitignore under a # MixinMCP auto-injected rules block.

You can edit these manually, but if you use the same name and do not change the configuration, they will be overwritten on project open. You can disable this override (or choose not to inject anything at all) in Settings → Tools → MixinMCP.

Tool reference

Source Navigation

Semantic Navigation

Bytecode Inspection

Mappings

Project Management

Decompilation cache details

How it works

• ./gradlew genDependencySources scans your resolved dependencies for JARs without a corresponding -sources.jar.
• Dependencies that do publish -sources.jar still get those jars unpacked into the same cache. Gradle/IntelliJ often use a remapped/transformed classes JAR on the classpath without attaching sources; mirroring fixes search and MCP tools for those libraries.
• Each missing-sources JAR is decompiled to ~/.cache/mixinmcp/decompiled/<hash>/.
• A manifest (manifest.json) tracks artifact identity so unchanged JARs are never re-decompiled (incremental).
• The IntelliJ plugin reads this cache on project open and after every Gradle sync, exposing the decompiled .java files as SyntheticLibrary roots. These are indexed and searchable just like real sources.

Decompilation is a blocking Gradle task, not a background IDE operation. This means tools never run against a half-populated cache. By the time you open the project, every dependency is searchable.

Memory tuning

Vineflower's SSA analysis can use significant memory on large JARs. The task defaults to 2 decompiler threads to keep memory usage reasonable.

Pre-flight check: Before decompiling large uncached JARs (≥15MB), the task checks whether the Gradle daemon heap is likely sufficient. If not, it blocks and prompts for confirmation. In non-interactive environments (CI, IntelliJ sync), the task fails with recommendations instead of hanging. Use --force to skip this check and proceed regardless:

# Manually set thread count. Setting threads=1 may cause decompilation to freeze entirely.
./gradlew genDependencySources --threads=3 # Default=2

# Skip OOM pre-flight confirmation (e.g. when you know heap is sufficient)
./gradlew genDependencySources --force

Add to your mod project's gradle.properties:

# Increase memory available to Gradle
org.gradle.jvmargs=-Xmx4g

# Disable parallelization (which may increase risk of OOM)
org.gradle.parallel=false

On large modded projects (50+ dependencies, some JARs over 100MB), you might need to set gradle process memory as high as -Xmx6g.

The task saves progress after each JAR, so if things do crash, just resync Gradle or run the task manually and Decompile will pick up where it left off.

Prefer native sources when available. Decompiled output lacks comments, meaningful parameter names, and local variable names. If a library publishes sources (Maven Central, JitPack, etc.), add the -sources classifier in your build script so IntelliJ attaches the real sources and MixinMCP skips decompilation for that JAR entirely.

Local development against an unpublished Gradle plugin build

# In the MixinMCP project
./gradlew :mixinmcp-gradle:publishToMavenLocal

Then swap maven { url = uri("https://maven.muon.rip/releases") } for mavenLocal() in your mod project's pluginManagement.repositories.

Building from Source

Building:

First clone the project and build:

git clone https://github.com/muon-rw/mixin-mcp.git
cd mixin-mcp
./gradlew buildPlugin # IntelliJ plugin
./gradlew build # Gradle Plugin

Recommended: Publish the Gradle Plugin locally

./gradlew publishToMavenLocal

Using:

Option 1: Run a sandboxed instance with the plugin installed

./gradlew runIde

Option 2: After buildPlugin, The plugin ZIP will be at build/distributions/mixin-mcp-<version>.zip.

In IntelliJ: Settings → Plugins → ⚙ → Install Plugin from Disk…