Maven Decoder MCP Server

Your agent guesses at library APIs it has never read. This makes it read them.

Lets AI agents read the actual source of any Maven dependency — decompiles jars from ~/.m2 or Maven Central, and diffs versions for breaking changes.

Ask an agent "I'm upgrading org.jsoup:jsoup from 1.17.2 to 1.23.2 — what breaks?" and without a way to read the jars it will answer from memory. With this server, compare_versions reads both jars and reports what actually changed:

Members are compared as declared, so one that moved to a supertype is reported as removed even though it may still be callable. The tool states this in its own output.

It works on artifacts that have no sources jar too: extract_class_info falls back to javap and returns parsed fields, methods, and bytecode version — which is exactly the case for the internal artifacts in a corporate Nexus.

Try it in one command

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

That installs the maven-code-search agent skill, which tells your agent when to reach for these tools. For a raw MCP server setup instead, see Installation.

🚀 Features

Core Functionality

• Jar File Analysis: Deep inspection of jar files including metadata, manifests, and structure
• Dependency Resolution: Complete dependency tree analysis with transitive dependencies
• Source Code Extraction: Extract source code from source jars or decompile bytecode
• Class Information: Detailed class signatures, methods, fields, and annotations
• Search Capabilities: Find classes, methods, and dependencies across all artifacts
• Version Management: Compare versions, find dependents, and track version conflicts

Online Maven Support

• Maven Central Search: Find artifacts and classes that are not installed locally
• Remote Version Listing: See every published version, not just the ones you have
• On-Demand Download: Fetch any artifact (jar, sources, POM) into a local cache
• Transparent Fallback: Every analysis tool automatically downloads a missing artifact, so decompiling a dependency you never installed just works
• Mirror Friendly: Point it at a corporate Nexus/Artifactory, with optional credentials
• Offline Mode: A single env var restores fully local, network-free behavior

Advanced Features

• Decompilation Support: Integrated support for multiple Java decompilers (CFR, Fernflower, Procyon)
• Conflict Analysis: Detect and analyze dependency version conflicts
• Repository Navigation: Browse and explore the local Maven repository structure
• Metadata Parsing: Extract and parse Maven POM files and metadata
• Service Discovery: Find and analyze Java services and SPI implementations
• Response Management: Intelligent pagination and summarization for large responses
• Method Extraction: Extract specific methods from large Java classes
• Integrity Checking: Downloads are verified against the repository's SHA-1 checksums

📦 Installation

Prerequisites

• Java 8+ (for decompilation features)
• Maven local repository (~/.m2/repository)
• One of: Python 3.8+, Node.js 14+, or Docker

🚀 Quick Install

One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/salitaba/maven-decoder-mcp/main/install.sh | bash

📋 Installation Methods

Method 1: uvx (Recommended)

# Install uv (if not installed)
curl -Ls https://astral.sh/uv/install.sh | sh
# Ensure your shell PATH is updated (restart shell or eval as printed by installer)

# Run the server via uvx (isolated, fast, no venv needed)
uvx maven-decoder-mcp

# Optional: pick a specific Python
# uvx --python 3.12 maven-decoder-mcp

Method 2: Node.js/npm

# Install globally
npm install -g maven-decoder-mcp

# Or install locally
npm install maven-decoder-mcp

# Run the server
maven-decoder-mcp
# or if installed locally: npx maven-decoder-mcp

Method 3: Docker

# Pull and run
docker run --rm -it \
  -v ~/.m2:/home/mcpuser/.m2 \
  -v $(pwd):/workspace \
  ali79taba/maven-decoder-mcp:latest

Method 4: From Source (Development)

# Clone repository
git clone https://github.com/salitaba/maven-decoder-mcp.git
cd maven-decoder-mcp

# Option A: Using Virtual Environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
pip install "git+https://github.com/modelcontextprotocol/python-sdk.git"
./setup_decompilers.sh

# Option B: System-wide Installation (not recommended)
./setup_decompilers.sh

Windows

For a source checkout, use Python 3.10 or newer and a JDK on PATH. From the repository root, create and activate a virtual environment in PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

# Point to your existing local Maven repository (drive-letter paths are supported)
$env:MAVEN_REPOSITORY = 'F:\data\repository'
maven-decoder-mcp

In Command Prompt (cmd.exe), activate with .venv\Scripts\activate.bat and set the repository with set "MAVEN_REPOSITORY=F:\data\repository" instead. These environment settings apply to programs launched from that terminal; set them in your MCP client's environment when it launches the server separately.

Remote downloads use a separate cache, resolved in this order (empty values are skipped):

1. MAVEN_DECODER_CACHE_DIR: the complete cache directory; no subdirectory is appended.
2. XDG_CACHE_HOME: append maven-decoder-mcp\repository.
3. LOCALAPPDATA: append maven-decoder-mcp\repository.
4. Otherwise, ~/.cache/maven-decoder-mcp/repository under your home directory.

On Windows, this usually means %LOCALAPPDATA%\maven-decoder-mcp\repository; XDG_CACHE_HOME still takes precedence if set. The cache uses Maven's directory layout but stays separate from the real local repository so downloads do not interfere with Maven builds. Setting MAVEN_REPOSITORY does not change the cache location.

🔧 Configuration

For Cursor IDE

Add to your ~/.cursor/mcp_servers.json:

{
  "maven-decoder": {
    "command": "uvx",
    "args": ["maven-decoder-mcp"]
  }
}

For Other MCP Clients

The server runs as a standard MCP server and can be integrated with any MCP-compatible client.

🧠 AI Agent Skill

This repository includes a maven-code-search agent skill that tells AI coding agents when and how to use this MCP for searching installed Maven package code.

npx skills add https://github.com/salitaba/maven-decoder-mcp --skill maven-code-search

The skill is located at skills/maven-code-search and is ready for skills.sh indexing after the repository is pushed.

🛠️ Available Tools

Local Analysis

Online (Maven Central)