JDT MCP服务器

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)

Navigation (4 Tools)

Code Analysis (4 Tools)

Creation (3 Tools)

Code Generation (9 Tools)

Refactoring (10 Tools)

Execution (6 Tools)

Documentation (4 Tools)

Code Quality (2 Tools)

Voraussetzungen

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

Unterstützte Plattformen

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/jdt-mcp/ und konfiguriert Claude Code automatisch.

Danach:

cd /dein/java-projekt
claude

Marketplace-Plugin (Claude Code)

Alternative zu install.sh: dieses Repo ist selbst ein Claude-Code-Plugin (.claude-plugin/plugin.json + .mcp.json). Über einen Marketplace installiert (/plugin marketplace add ... bzw. das Marketplace-übliche /plugin install) bringt das Plugin die MCP-Server-Registrierung selbst mit — es ist kein separates install.sh nötig, um jdt-mcp als Server bekannt zu machen.

Der Server braucht trotzdem den Launcher-Binary. Die Plugin-.mcp.json startet ihn über einen absoluten, ${HOME}-expandierten Pfad (${HOME}/.local/share/jdt-mcp/bin/jdt-mcp) statt über den bloßen Befehlsnamen jdt-mcp — der Prozess, der MCP-Server startet, hat nicht zwangsläufig ~/.local/bin im PATH (viele .profile-Setups erweitern PATH nur für Login-Shells). Dafür läuft beim Session-Start ein SessionStart-Hook (hooks/ensure-server.sh): fehlt der Launcher (~/.local/bin/jdt-mcp bzw. ~/.local/share/jdt-mcp/bin/jdt-mcp), führt er install.sh aus dem Plugin-Verzeichnis aus — mit JDTMCP_SKIP_CLAUDE=1, installiert also nur den Launcher, ohne zusätzlich claude mcp add aufzurufen (das übernimmt bereits die .mcp.json des Plugins). Fehlt Java 21+ oder Netzzugriff, meldet der Hook das als Kontext-Hinweis in der Session, statt die Session zu blockieren (Exit 0 in jedem Fall, mit Timeout um den install.sh-Aufruf). install.sh selbst serialisiert parallele Läufe (z.B. zwei gleichzeitig gestartete Sessions ohne Launcher) über einen mkdir-Lock mit Erkennung verwaister Locks — eine zweite Session wartet kurz und überspringt Download/Entpacken dann, statt zwei Installationen gegeneinander laufen zu lassen.

Schon eine Standalone-Installation per install.sh vorhanden (also jdt-mcp bereits via claude mcp add -s user jdt-mcp ... im User-Scope registriert)? Dann NICHT zusätzlich das Marketplace-Plugin aktivieren — beide Registrierungen sind unterschiedlich benannt (mcp__jdt-mcp__* im User-Scope vs. mcp__plugin_jdt-mcp-server_jdt-mcp__* im Plugin-Scope) und würden nebeneinander laufen, also zwei separate Server-Prozesse gegen denselben Eclipse-Workspace eines Arbeitsverzeichnisses starten. Der Workspace-Mutation-Lock im Server ist ein prozessinterner ReentrantLock und schützt nicht vor einer zweiten JVM auf demselben Workspace. Wer beides ausprobiert hat: entweder das Plugin deaktivieren, oder die User-Scope-Registrierung entfernen (claude mcp remove -s user jdt-mcp) und beim Plugin bleiben.

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).

Der Launcher hieß bis v1.1.0 jdtls-mcp. Beim Update von einer älteren Version entfernt install.sh automatisch die Alt-Installation unter ~/.local/share/jdtls-mcp (~180 MB) sowie den alten Symlink ~/.local/bin/jdtls-mcp. Wer den Pfad manuell in claude mcp add eingetragen hatte (statt über dieses Script), muss die Registrierung selbst auf jdt-mcp (siehe unten) umstellen.

Installierte Version prüfen:

jdt-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/jdt-mcp ~/.local/bin/jdt-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/jdt-mcp
tar xzf jdt-mcp-linux.gtk.x86_64.tar.gz -C ~/.local/share/jdt-mcp

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

Manuelle Installation (Windows)

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

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

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

Erweiterte Optionen

# HTTP-Modus (für Debugging)
jdt-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
• Classpath-Auffrischung: Hat sich die pom.xml eines Moduls (oder eine Parent-pom.xml) seit der letzten Auflösung geändert, löst der Server die Abhängigkeiten dieses Moduls beim Start neu auf — sonst würde er gegen den Stand des letzten Imports bauen
• Vollbau nach dem Wiederöffnen: Sobald Projekte aus einer früheren Sitzung wiedergeöffnet werden, baut der Server den Workspace einmal vollständig, damit kein gespeicherter Fehler-Marker der letzten Sitzung überlebt
• 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")

Git-Worktrees und zweite Checkouts

Ein Eclipse-Projekt ist über seinen Namen identifiziert, und der Name kommt aus dem Modulverzeichnis. Ein zweiter Checkout desselben Repositories — typisch ein git-Worktree neben dem Haupt-Checkout — bringt deshalb Namen mit, die der Workspace schon kennt. Der Server verwendet einen vorhandenen Namen nur wieder, wenn das Projekt bereits in genau diesem Verzeichnis liegt. Sonst bekommt das neue Projekt den Verzeichnisnamen des importierten Pfads als Suffix:

jdt_import_project(path="/home/dev/arknet-worktrees/126")
→ arknet-core@126, arknet-app@126, …   (Haupt-Checkout bleibt arknet-core, arknet-app, …)

• jdt_list_projects zeigt je Projekt location (das gebaute Verzeichnis) und importRoot (den Checkout, mit dem es importiert wurde) — vor einem Build prüfen, ob der Treffer im eigenen Baum liegt
• Geschwistermodule werden innerhalb des eigenen Checkouts aufgelöst: arknet-app@126 referenziert arknet-core@126, nicht arknet-core
• jdt_maven_build und jdt_run_tests melden das Verzeichnis (location), in dem sie gelaufen sind
• Ein unbekannter projectName wird mit der Liste der bekannten Projekte samt Pfaden beantwortet, statt still gegen einen anderen Baum zu bauen
• Der Server importiert beim Start nur sein Arbeitsverzeichnis; ein Worktree muss einmal per jdt_import_project dazukommen

Workspace-Umgebungsvariablen

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; bei einem zweiten Checkout mit Suffix, z. B. core@126 — location prüfen)
• 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: jdt-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

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/jdt-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/jdt-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/jdt-mcp-binary]

Code-Generierungs-Tests (End-to-End)

Importieren tests/fixtures/fixture-parent und lassen jdt_implement_interface auf Deklarations-Köpfe los, die eine reine Textsuche aushebeln (Record mit Komponentenliste, sealed-Klasse mit permits, Kommentar mit { im Kopf, verschachtelte Generics in einer bestehenden implements-Liste). Zwei Fälle prüfen die Ablehnung ungeeigneter Ziele (Annotationstyp, Interface): Fehlerantwort statt Schreibzugriff, Datei bleibt byte-identisch. Geprüft wird die Datei auf der Festplatte, anschließend wird sie mit javac übersetzt:

tests/codegen-test.sh [path/to/jdt-mcp-binary]

Build-Path-Tests (End-to-End)

Importieren tests/fixtures/fixture-parent und tests/fixtures/fixture-badclasspath (fehlende Library im .classpath) und prüfen, dass jdt_get_compilation_errors das konkrete Build-Path-Problem meldet und jdt_maven_update_project Geschwistermodule als Projektreferenz führt statt als ~/.m2-Jar — auch transitiv aufgelöste:

Die Reaktor-Geschwister müssen dafür als Jar auflösbar sein, das Skript installiert sie deshalb mit ihren echten Koordinaten (org.fixture:*) ins lokale Maven-Repository, sichert einen vorhandenen org/fixture-Baum vorher und stellt den Ausgangszustand am Ende wieder her — auch bei Strg-C. Das Repository ist dabei nicht isoliert: der Server ruft mvn dependency:build-classpath selbst auf und benutzt das konfigurierte lokale Repository, ein -Dmaven.repo.local im Test würde also auseinanderlaufen. Der Pfad wird deshalb bei Maven erfragt statt überschrieben; echte Isolation ist #124. Ohne Netz werden die jdt_maven_update_project-Tests übersprungen statt rot; JDTMCP_REQUIRE_MAVEN=1 macht daraus einen harten Fehler.

tests/buildpath-test.sh [path/to/jdt-mcp-binary]

Worktree-Test (End-to-End)

Startet den Server in einer Kopie von tests/fixtures/fixture-parent und importiert eine zweite Kopie als Worktree (fixture-parent-worktrees/126). Prüft, dass die Worktree-Module als fixture-api@126 usw. mit Pfad im Worktree erscheinen, dass jdt_list_projects beide Checkouts über location/importRoot unterscheidet, dass Geschwister innerhalb des eigenen Checkouts referenziert werden, dass jdt_maven_build sein Verzeichnis nennt, dass ein im Worktree eingebauter Compile-Fehler nur dort gemeldet wird und dass ein unbekannter projectName die bekannten Projekte mit Pfaden zurückgibt:

tests/worktree-test.sh [path/to/jdt-mcp-binary]

Compiler-Compliance-Test (End-to-End)

Importiert tests/fixtures/fixture-java25 (maven.compiler.release=25, nutzt Module-Import-Deklarationen) und prüft, dass jdt_get_project_structure compliance=25 meldet und jdt_get_compilation_errors sauber ist — unabhängig davon, mit welcher JVM der Server selbst gestartet wurde:

tests/compliance-test.sh [path/to/jdt-mcp-binary]

Unit-Tests

org.naturzukunft.jdt.mcp ist ein Tycho-eclipse-plugin-Modul ohne Tycho-Surefire-Testfragment. Klassen ohne Eclipse/OSGi-Abhängigkeit (z. B. MavenCompilerCompliance) werden stattdessen mit einem eigenständigen JUnit-5-Runner getestet, der gegen bereits lokal gecachte JUnit-Jars kompiliert (Quellen unter org.naturzukunft.jdt.mcp/unit-tests/java/, außerhalb des Tycho-Reactors):

tests/run-unit-tests.sh

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