Eclipse JDT MCP Server

Note: This repository moved to GitHub in September 2026. The former home on Forgejo (git.changinggraph.org/ai-tools/jdt-mcp-server) is archived; issue numbers were preserved.

An MCP server (Model Context Protocol) that exposes Eclipse JDT features to AI coding assistants like Claude Code, Cursor, and others. It provides 52 tools across 9 categories — covering navigation, refactoring, code generation, test execution, and more. Runs as a standalone CLI (stdio) without requiring the Eclipse IDE. Install with a single curl | bash command, then use it from any Java project.

---

MCP-Server (Model Context Protocol) für Java Development Tools (JDT). Stellt JDT-Funktionen für KI-Coding-Assistenten wie Claude Code, Cursor und andere bereit.

Standalone CLI - Läuft ohne Eclipse IDE, direkt als MCP-Subprocess (stdio). Einfach installieren, in ein Java-Projekt wechseln, Claude Code starten.

Inspiriert von: Spring Tools 5 embedded MCP Server von Martin Lippert

Features

Der Server stellt 52 MCP-Tools in 9 Kategorien bereit:

Project Info (5 Tools)

Tool	Beschreibung
jdt_list_projects	START HERE: Alle Java-Projekte im Workspace auflisten
jdt_get_classpath	Classpath eines Projekts abrufen (Source-Folder, Libraries, Output-Folder)
jdt_get_compilation_errors	Kompilierungsfehler und Warnungen mit Datei, Zeile und Nachricht
jdt_get_project_structure	Projektstruktur-Übersicht (Java-Version, Source-Folder, Packages)
jdt_refresh_project	WICHTIG: Workspace aktualisieren nach externen Dateiänderungen (Write/Edit, git)

Navigation (4 Tools)

Tool	Beschreibung
jdt_find_type	Typen nach Namensmuster suchen (*Service, User*)
jdt_get_method_signature	Methodensignaturen mit Parametern, Rückgabetyp, Modifiern
jdt_find_implementations	Alle Implementierungen eines Interfaces oder Subklassen finden
jdt_find_callers	Alle Aufrufer einer Methode finden

Code Analysis (4 Tools)

Tool	Beschreibung
jdt_parse_java_file	Java-Datei parsen: Package, Imports, Typen, Methoden, Felder mit Offsets
jdt_get_type_hierarchy	Typhierarchie: Superklassen, Interfaces, Subklassen
jdt_find_references	Alle Verwendungen einer Klasse/Methode/Feld im Workspace finden
jdt_get_source_range	QUELLCODE LESEN: Tatsächlichen Code einer Methode/Klasse als Text zurückgeben

Creation (3 Tools)

Tool	Beschreibung
jdt_create_class	Neue Java-Klasse erstellen
jdt_create_interface	Neues Java-Interface erstellen
jdt_create_enum	Neues Java-Enum mit Konstanten erstellen

Code Generation (9 Tools)

Tool	Beschreibung
jdt_add_method	Methode zu bestehender Klasse hinzufügen
jdt_add_field	Feld zu bestehender Klasse hinzufügen
jdt_add_import	Import-Statements hinzufügen (korrekte Platzierung, keine Duplikate)
jdt_implement_interface	Interface implementieren und Method-Stubs generieren
jdt_generate_getters_setters	Getter/Setter generieren (überspringt existierende)
jdt_generate_constructor	Konstruktor(en) generieren (optional No-Args für JPA/Jackson)
jdt_generate_equals_hashcode	equals() und hashCode() mit java.util.Objects generieren
jdt_generate_tostring	toString() generieren: User{id=1, name='John'}
jdt_generate_delegate_methods	Delegation Pattern: Methoden die an ein anderes Objekt delegieren

Refactoring (10 Tools)

Tool	Beschreibung
jdt_rename_element	Sicheres Umbenennen: Klasse/Methode/Feld umbenennen, alle Referenzen aktualisieren
jdt_extract_method	Code in neue Methode extrahieren (Parameter/Rückgabetyp automatisch erkannt)
jdt_move_type	Klasse in anderes Package verschieben, alle Imports aktualisieren
jdt_organize_imports	Imports aufräumen: unbenutzte entfernen, sortieren
jdt_inline	Variable/Ausdruck inlinen (Gegenteil von Extract)
jdt_extract_interface	Interface aus Klasse extrahieren
jdt_change_method_signature	Methodensignatur ändern, alle Aufrufer aktualisieren
jdt_convert_to_lambda	Anonyme Klasse zu Lambda-Ausdruck konvertieren
jdt_encapsulate_field	Feld kapseln: private machen + Getter/Setter, alle Zugriffe aktualisieren
jdt_introduce_parameter	Lokale Variable als Methodenparameter extrahieren

Execution (6 Tools)

Tool	Beschreibung
jdt_maven_build	Maven-Build mit Auto-Detection von Maven Wrapper und Java-Version
jdt_run_main	Java-Klasse mit main() ausführen, stdout/stderr erfassen
jdt_list_tests	Tests auflisten (pattern='unit' für *Test.java, 'integration' für *IT.java)
jdt_run_tests	Tests ausführen mit strukturiertem JSON-Output
jdt_start_tests_async	Lang laufende Tests asynchron starten (>30s, z.B. Spring Boot)
jdt_get_test_result	Status/Ergebnis eines asynchronen Testlaufs abrufen

Documentation (4 Tools)

Tool	Beschreibung
jdt_get_javadoc	Javadoc für Klasse/Methode/Feld abrufen
jdt_get_annotations	Alle Annotationen eines Elements mit Werten abrufen
jdt_find_annotated_elements	Alle Elemente mit bestimmter Annotation finden (@Service, @Test, @Entity)
jdt_generate_javadoc	Javadoc-Kommentar generieren mit @param, @return, @throws

Code Quality (2 Tools)

Tool	Beschreibung
jdt_find_unused_code	Unbenutzte Imports, private Felder und Methoden finden
jdt_find_dead_code	Unerreichbaren Code finden (nach return/throw, tote Branches)

Voraussetzungen

• Java 21+
• Maven 3.9+ (nur für Build aus Source)

Unterstützte Plattformen

Plattform	Architektur	Install-Script	Manuell
Linux	x86_64, aarch64	curl ... | bash	tar.gz
macOS	x86_64, aarch64 (Apple Silicon)	curl ... | bash	tar.gz
Windows	x86_64	-	zip + jdtls-mcp.cmd

Installation (Linux & macOS)

curl -sSL https://github.com/hauschel-ai-tools/jdt-mcp-server/raw/main/install.sh | bash

Das Script erkennt OS und Architektur, lädt die neueste Version herunter, installiert nach ~/.local/share/jdtls-mcp/ und konfiguriert Claude Code automatisch.

Danach:

cd /dein/java-projekt
claude

Update

Einfach den gleichen Befehl erneut ausführen:

curl -sSL https://github.com/hauschel-ai-tools/jdt-mcp-server/raw/main/install.sh | bash

Das Script erkennt die bestehende Installation und zeigt den Update-Pfad an (z.B. Update: 0.2.1 -> 0.2.2).

Installierte Version prüfen:

jdtls-mcp --version

Installation aus lokalem Build

git clone https://github.com/hauschel-ai-tools/jdt-mcp-server.git
cd jdt-mcp-server
./install-local.sh

Deinstallation

curl -sSL https://github.com/hauschel-ai-tools/jdt-mcp-server/raw/main/uninstall.sh | bash

Oder manuell:

rm -rf ~/.local/share/jdtls-mcp ~/.local/bin/jdtls-mcp
claude mcp remove jdt-mcp

Manuelle Installation (Linux/macOS)

# Archiv herunterladen von:
# https://github.com/hauschel-ai-tools/jdt-mcp-server/releases

# Entpacken
mkdir -p ~/.local/share/jdtls-mcp
tar xzf jdtls-mcp-linux.gtk.x86_64.tar.gz -C ~/.local/share/jdtls-mcp

# Claude Code konfigurieren
claude mcp add -s user jdt-mcp ~/.local/share/jdtls-mcp/bin/jdtls-mcp

Manuelle Installation (Windows)

# ZIP-Archiv herunterladen von:
# https://github.com/hauschel-ai-tools/jdt-mcp-server/releases

# Entpacken (z.B. nach %LOCALAPPDATA%\jdtls-mcp)
Expand-Archive jdtls-mcp-win32.win32.x86_64.zip -DestinationPath "$env:LOCALAPPDATA\jdtls-mcp"

# Claude Code konfigurieren
claude mcp add -s user jdt-mcp "$env:LOCALAPPDATA\jdtls-mcp\bin\jdtls-mcp.cmd"

Erweiterte Optionen

Umgebungsvariable	Beschreibung	Standard
JDTMCP_TRANSPORT	Transport: stdio oder http	stdio
JDTMCP_WORKSPACE	Eclipse Workspace-Verzeichnis	~/.jdt-mcp/workspaces/<hash>
JAVA_HOME	Java-Installation	System-Java

# HTTP-Modus (für Debugging)
jdtls-mcp --http

Workspace-Management

Der JDT MCP Server verwaltet einen Eclipse Workspace pro Arbeitsverzeichnis. Der Workspace enthält die JDT-Metadaten (Index, Classpath, Build-State) — die eigentlichen Projektdateien bleiben an ihrem Platz.

Wie Workspaces funktionieren

~/mein-java-projekt/          ← Arbeitsverzeichnis (user.dir)
  ├── pom.xml                 ← Maven-Projekt wird automatisch importiert
  ├── modul-a/                ← Multi-Module: jedes Modul wird ein eigenes JDT-Projekt
  └── modul-b/

~/.jdt-mcp/
  ├── workspaces/<md5-hash>/  ← Eclipse Workspace (pro Arbeitsverzeichnis)
  │   └── .metadata/          ← JDT-Index, Build-State, Projekt-Referenzen
  └── jdt-mcp-mein-java-projekt.log  ← Log (pro Arbeitsverzeichnis)

• Automatischer Import: Beim Start importiert der Server alle Projekte aus dem Arbeitsverzeichnis (Maven, Gradle, Eclipse .project)
• Persistenter Workspace: Der Workspace bleibt zwischen Neustarts erhalten — kein erneuter Import nötig
• Ein Workspace pro Verzeichnis: Jedes Arbeitsverzeichnis bekommt einen eigenen, isolierten Workspace (MD5-Hash des Pfads)

Workspace zurücksetzen

Falls der Workspace korrupt ist oder Projekte nicht korrekt erkannt werden:

# Workspace-Verzeichnis für aktuelles Arbeitsverzeichnis finden
HASH=$(printf '%s' "$PWD" | md5sum | cut -d' ' -f1)
rm -rf ~/.jdt-mcp/workspaces/$HASH

# Server neu starten (Claude Code neu starten oder Session beenden)

Beim nächsten Start wird der Workspace automatisch neu erstellt und alle Projekte frisch importiert.

Zusätzliche Projekte importieren

Projekte die nicht im Arbeitsverzeichnis liegen, können nachträglich importiert werden:

jdt_import_project(path="/pfad/zum/anderen/projekt")

Workspace-Umgebungsvariablen

Variable	Beschreibung	Standard
JDTMCP_WORKSPACE	Eigenes Workspace-Verzeichnis setzen	~/.jdt-mcp/workspaces/<hash>

Logs

Jede Server-Instanz loggt in eine eigene Datei basierend auf dem Arbeitsverzeichnis:

# Logs für ein bestimmtes Projekt anschauen
tail -f ~/.jdt-mcp/jdt-mcp-mein-java-projekt.log

Typischer Workflow

1. Start: jdt_list_projects aufrufen um verfügbare Projekte zu sehen
2. Erkunden: jdt_get_project_structure für Übersicht, jdt_find_type zum Suchen
3. Analysieren: jdt_parse_java_file für Datei-Details, jdt_find_references für Verwendungen
4. Ändern: jdt_create_class, jdt_generate_*, jdt_rename_element
5. Aktualisieren: jdt_refresh_project nach externen Änderungen
6. Bauen/Testen: jdt_maven_build, jdt_run_tests

Parameter-Formate

• projectName: Eclipse-Projektname (von jdt_list_projects)
• className (fully qualified): com.example.MyClass
• methodName/fieldName: com.example.MyClass#methodName
• filePath: Absoluter Pfad zur Java-Datei
• offset: Zeichenposition in Datei (von jdt_parse_java_file)

Troubleshooting

Server startet nicht

1. Log prüfen: ~/.jdt-mcp/jdt-mcp-<projektname>.log
2. Java-Version prüfen: java -version (21+ erforderlich)
3. Binary testen: jdtls-mcp direkt ausführen, stderr-Ausgabe beobachten

Veraltete Daten nach Dateiänderungen

jdt_refresh_project aufrufen! Der Server erkennt externe Änderungen nicht automatisch.

Server-JVM bleibt nach Session-Ende übrig

Die JVM beendet sich selbst, sobald der Client stdin schließt, der Launcher-Wrapper stirbt oder ein Signal weitergeleitet wird. Bleibt trotzdem ein java … org.naturzukunft.jdt.mcp.headless-Prozess zurück, ist er meist gestoppt (Zustand T in ps) und braucht erst kill -CONT, dann kill -TERM:

pkill -CONT -f jdtmcp.headless; pkill -TERM -f jdtmcp.headless

Tests laufen zu lange

jdt_start_tests_async statt jdt_run_tests verwenden. MCP-Client-Timeout ist 60s.

Bekannte Einschränkungen

Einschränkung	Betroffenes Tool	Ursache	Issue
Projekte mit JUnit Platform 1.x (JUnit 5) schlagen bei jdt_run_tests/jdt_start_tests_async fehl	jdt_run_tests, jdt_start_tests_async	NoClassDefFoundError: org/junit/platform/engine/OutputDirectoryCreator im gebündelten JUnit5-Runner — dessen Eclipse-JDT-Loader-Version erwartet eine neuere JUnit-Platform-API als 1.x liefert. JUnit Platform 1.x wird daher nicht unterstützt; auf JUnit 6 heben. JUnit 4 und JUnit 6 werden automatisch am Projekt-Classpath erkannt und funktionieren. Workaround für JUnit 5: jdt_maven_build(goals="test")	#71
Unbenutzte package-private Felder werden nicht erkannt	jdt_find_unused_code	JDT erkennt nur unbenutzte private Members, nicht package-private	#72
jdt_inline kann bestimmte statische Factory-Methoden nicht inlinen	jdt_inline	JDT-Bug: InlineMethodRefactoring.create() liefert null für manche Method-Patterns im Headless-Modus	#81
jdt_implement_interface: implements-Klausel wird per String eingefügt statt ASTRewrite	jdt_implement_interface	Kann bei komplexen Klassen-Deklarationen (verschachtelte Generics, mehrere Annotations) fehlschlagen	#101

Entwicklung

Smoke Tests

Der Server hat stdio-basierte Smoke Tests, die den MCP-Protokoll-Handshake und grundlegende Tool-Aufrufe prüfen:

tests/smoke-test.sh [path/to/jdtls-mcp-binary]

Ohne Argument wird das Binary aus dem lokalen Build verwendet.

Lifecycle Tests

Prüfen, dass die Server-JVM ihren Client nie überlebt (stdin-EOF, Signal-Weiterleitung, Parent-Death-Erkennung, eigene Prozessgruppe):

tests/lifecycle-test.sh [path/to/jdtls-mcp-binary]

Refactoring-Tests (End-to-End)

Importieren tests/fixtures/fixture-parent und tests/fixtures/fixture-external als zwei getrennte Projekte und prüfen nach jedem Refactoring den Zustand auf der Festplatte, nicht die Tool-Antwort — im Headless-Modus meldete ein Refactoring schon Erfolg, während die Änderungen nur im Puffer standen:

tests/refactoring-test.sh [path/to/jdtls-mcp-binary]

Lizenz

Apache License 2.0

Mitwirken

Beiträge sind willkommen! Bitte erstelle einen Issue oder Pull Request: https://github.com/hauschel-ai-tools/jdt-mcp-server

Built by

Fred Hauschel – freelance Java architect & quality engineer, Munich. IT freelancer since 1999, working AI-augmented. → https://hauschel.de