Java Class Decompiler MCP Server

A Model Context Protocol (MCP) server that decompiles Java classes from Maven project dependencies using the CFR decompiler.

Features

• Decompile Java Classes: Extract source code from compiled Java classes in Maven dependencies
• Find JAR Paths: Quickly locate which JAR file contains a specific class
• Maven Integration: Automatically detects Maven wrapper (mvnw), MAVEN_HOME, or system Maven
• Intelligent Caching: Persistent file system cache to avoid redundant decompilation
• Fuzzy Matching: Suggests similar class names when exact matches aren't found
• Index Building: Fast lookups by building an index of all classes in dependencies

Installation

Using npx (Recommended)

No installation required - just run:

npx java-class-decompiler-mcp-maven

Global Installation

Install globally to use from anywhere:

npm install -g java-class-decompiler-mcp-maven
java-class-decompiler-mcp-maven

Project Dependency

Install as a dependency in your project:

npm install java-class-decompiler-mcp-maven

Then add to your Claude Desktop configuration (see Configuration below).

Upgrading

To upgrade to the latest version:

Global Installation:

npm update -g java-class-decompiler-mcp-maven

Project Dependency:

npm update java-class-decompiler-mcp-maven

Using npx: No action needed - npx automatically uses the latest version each time it runs.

Usage

Configuration

Quick Setup (Command Line)

The claude mcp add command allows you to configure the MCP server with different scopes and environment variables.

Understanding Scopes:

• --scope project - Project-specific configuration

  • Config location: <project-root>/.claude/mcp_settings.json
  • Best for: Team collaboration or project-specific setups

• --scope user - User-wide configuration (recommended for Java developers)

  • Config location: ~/.claude/mcp_settings.json
  • Best for: Working with multiple Maven projects

• --scope local - Local configuration (default)

  • Config location: ./.claude/mcp_settings.json
  • Best for: Temporary testing

Installation Examples:

User scope with environment variables (Recommended):

claude mcp add --transport stdio --scope user java-class-decompiler-mcp-maven \
  -e MAVEN_HOME=/absolute/path/to/maven \
  -e JAVA_HOME=/absolute/path/to/java-jdk \
  -- npx -y java-class-decompiler-mcp-maven

Project scope:

claude mcp add --transport stdio --scope project java-class-decompiler-mcp-maven \
  -e MAVEN_HOME=/absolute/path/to/maven \
  -- npx -y java-class-decompiler-mcp-maven

Local scope (for testing):

claude mcp add --transport stdio --scope local java-class-decompiler-mcp-maven -- npx -y java-class-decompiler-mcp-maven

Environment Variables with -e:

• MAVEN_HOME - Path to Maven installation (optional, auto-detected if not set)
• JAVA_HOME - Path to Java JDK installation (optional, uses system default if not set)

Which Scope Should You Use?

• Use --scope user if you work with multiple Maven projects (configure once, use everywhere)
• Use --scope project for team collaboration or project-specific configuration
• Use --scope local for temporary testing

Manual Configuration

Alternatively, you can manually add the configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Using npx (Recommended)

{
  "mcpServers": {
    "java-class-decompiler": {
      "command": "npx",
      "args": ["java-class-decompiler-mcp-maven"],
      "cwd": "/absolute/path/to/your/maven/project",
      "env": {
        "MAVEN_HOME": "/absolute/path/to/maven",
        "JAVA_HOME": "/absolute/path/to/java-jdk"
      }
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "java-class-decompiler": {
      "command": "java-class-decompiler-mcp-maven",
      "cwd": "/absolute/path/to/your/maven/project",
      "env": {
        "JAVA_HOME": "/absolute/path/to/java-jdk"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "java-class-decompiler": {
      "command": "node",
      "args": ["/absolute/path/to/java-class-decompiler-mcp-maven/dist/index.js"],
      "cwd": "/absolute/path/to/your/maven/project",
      "env": {
        "MAVEN_HOME": "/absolute/path/to/maven",
        "JAVA_HOME": "/absolute/path/to/java-jdk"
      }
    }
  }
}

Configuration Options:

• command: The command to run (use npx for easy installation, or the full path to node for local installs)
• args: Arguments passed to the command
• cwd (optional): Working directory - should be your Maven project root (containing pom.xml). If not provided, defaults to the current working directory when the server starts. It's strongly recommended to explicitly set this to ensure the server runs in the correct project directory.
• env (optional): Environment variables
  • MAVEN_HOME (optional): Path to Maven installation directory. If not set, the server will automatically search for Maven in this order:
    1. Maven wrapper (./mvnw or mvnw.cmd) - highest priority, ensures project-specific Maven version
    2. MAVEN_HOME environment variable
    3. System Maven in PATH (mvn)
  • JAVA_HOME (optional): Path to Java JDK installation directory. If not set, uses the system default Java from PATH or the JAVA_HOME environment variable. This is used for running the CFR decompiler.

Available Tools

decompile_class

Decompile a Java class and return its source code.

Parameters:

• className (string, required): Fully qualified Java class name (e.g., "com.example.MyClass")
• forceRefresh (boolean, optional): Bypass cache and force re-decompilation (default: false)

Example:

Decompile the class java.util.ArrayList

get_cache_stats

Get statistics about the decompilation cache and class index.

Returns:

• Cache entry count
• Cache directory location
• Total indexed classes
• Index build status

clear_cache

Clear the decompilation cache (does not clear the class index).

get_jar_path_by_class

Get the JAR file path where a specific Java class is located.

Parameters:

• className (string, required): Fully qualified Java class name (e.g., "com.example.MyClass")

Returns:

• className (string): The queried class name
• jarPath (string | null): Absolute path to the JAR file, or null if not found
• found (boolean): Whether the class was found in the index
• message (string): Human-readable result message

Example:

Find the JAR path for org.springframework.core.io.Resource

Response when found:

{
  "className": "org.springframework.core.io.Resource",
  "jarPath": "/Users/user/.m2/repository/org/springframework/spring-core/6.1.0/spring-core-6.1.0.jar",
  "found": true,
  "message": "Found org.springframework.core.io.Resource in /Users/user/.m2/repository/org/springframework/spring-core/6.1.0/spring-core-6.1.0.jar"
}

Response when not found:

{
  "className": "com.example.NonExistent",
  "jarPath": null,
  "found": false,
  "message": "Class com.example.NonExistent not found in index"
}

Use Cases:

• Verify dependency sources and versions
• Debug class loading issues
• Understand project structure without decompiling
• Quick class location queries

index_jar

Index JAR files from the pom.xml in the current directory. This will build a class index from all dependencies in the pom.xml.

Parameters: None

Returns:

• projectRoot (string): Path to the project directory
• jarCount (number): Number of JARs indexed
• classCount (number): Number of classes found
• jars (array): First 10 JAR paths (for summary)
• message (string): Success message with statistics

list_indexed_jars

List all JAR files that have been indexed.

Parameters: None

Returns:

• count (number): Number of indexed JAR files
• jarPaths (array): Array of absolute paths to indexed JAR files
• message (string): Summary message

search_classes

Search for classes by pattern in the class index.

Parameters:

• pattern (string, required): Search pattern (case-insensitive substring match)

Returns:

• pattern (string): The search pattern used
• count (number): Number of matching classes
• classes (array): Array of matching class names (limited to 100)
• message (string): Summary of search results

Example:

Search for classes containing "SpringApplication"

Error Handling

Maven Not Found

If Maven is not detected, the server will return:

{
  "error": "MAVEN_NOT_INSTALLED",
  "message": "Maven command not found. Checked: MAVEN_HOME, mvnw, PATH",
  "searchedLocations": [...],
  "suggestion": "Please install Maven from https://maven.apache.org/download.cgi"
}

Class Not Found with Fuzzy Suggestions

If a class is not found, similar classes are suggested:

{
  "error": "CLASS_NOT_FOUND",
  "className": "com.example.MyClas",
  "message": "Exact match not found. Found 2 similar classes.",
  "suggestions": [
    {
      "className": "com.example.MyClass",
      "similarity": 0.95,
      "jarPath": "/path/to/example.jar"
    }
  ],
  "totalMatches": 2
}

Decompilation Failed

If CFR cannot decompile a class:

{
  "error": "DECOMPILATION_FAILED",
  "className": "com.example.ObfuscatedClass",
  "reason": "CFR unable to decompile",
  "jarPath": "/path/to/example.jar"
}

Logging

Logs are written to .mcp/java-decompiled/logs/ with daily rotation:

• YYYY-MM-DD.log - Main log file
• YYYY-MM-DD-error.log - Error-only log file

Technology Stack

• Runtime: Node.js 18+
• Language: TypeScript 5.x
• MCP SDK: @modelcontextprotocol/sdk
• Decompiler: CFR 0.152
• Archive: adm-zip for JAR reading

Maven Detection Priority

The server searches for Maven in this order:

1. Maven wrapper (./mvnw or mvnw.cmd) - highest priority, ensures project-specific Maven version
2. MAVEN_HOME environment variable (can be set in system environment or Claude Desktop config)
3. System Maven in PATH (mvn)

Setting MAVEN_HOME

You can configure MAVEN_HOME in two ways:

Option 1: System Environment Variable

# macOS/Linux
export MAVEN_HOME=/path/to/maven
export PATH=$MAVEN_HOME/bin:$PATH

# Windows
set MAVEN_HOME=C:\path\to\maven
set PATH=%MAVEN_HOME%\bin;%PATH%

Option 2: Claude Desktop Config (Recommended) Add the env section to your MCP server configuration:

{
  "mcpServers": {
    "java-decompiler": {
      "command": "node",
      "args": ["/absolute/path/to/java-class-decompiler-mcp-maven/dist/index.js"],
      "cwd": "/absolute/path/to/your/maven/project",
      "env": {
        "MAVEN_HOME": "/absolute/path/to/maven"
      }
    }
  }
}

Note: Maven Wrapper (mvnw) takes precedence over MAVEN_HOME. If your project has a Maven Wrapper, it will be used regardless of the MAVEN_HOME setting.

Requirements

• Node.js 18 or higher
• Java 8 or higher (for running CFR)
• Maven installation (for dependency resolution)
• A valid Maven project with pom.xml

License

MIT

Credits

• CFR Decompiler by Lee Benfield
• Model Context Protocol by Anthropic