LSP4J-MCP Server
A Java MCP (Model Context Protocol) server that wraps JDTLS (Eclipse JDT Language Server) using LSP4J to provide Java IDE features to AI assistants like Claude.
Features
This MCP server exposes the following tools:
Prerequisites
- Java 21+
- Maven 3.8+
- JDTLS installed (e.g., via Homebrew:
brew install jdtls)
Build
mvn clean package
This creates a shaded JAR at target/lsp4j-mcp-1.0.0-SNAPSHOT.jar.
Usage
Option 1: Run Script
./run.sh /path/to/your/java/project
Option 2: Direct Java Command
java -jar target/lsp4j-mcp-1.0.0-SNAPSHOT.jar <workspace-path> <jdtls-command>
Example:
java -jar target/lsp4j-mcp-1.0.0-SNAPSHOT.jar /Users/me/projects/myapp jdtls
Option 3: Claude Code MCP Configuration
Add to your .mcp.json:
{
"mcpServers": {
"java-lsp": {
"command": "java",
"args": [
"-jar",
"/path/to/LSP4J-MCP/target/lsp4j-mcp-1.0.0-SNAPSHOT.jar",
"/path/to/your/java/project",
"jdtls"
],
"env": {
"LOG_FILE": "/tmp/lsp4j-mcp.log"
}
}
}
}
Option 4: Docker
Build the multi-stage image. It includes Java 21, the shaded MCP server, and a pinned Eclipse JDTLS distribution:
docker build -t lsp4j-mcp:local .
Run it over stdio and mount the Java project at /workspace:
docker run --rm -i \
--mount type=bind,source=/absolute/path/to/java/project,target=/workspace \
lsp4j-mcp:local
On Linux, use the host UID/GID when the language server needs to write project metadata into the mounted workspace:
docker run --rm -i \
--user "$(id -u):$(id -g)" \
--mount type=bind,source=/absolute/path/to/java/project,target=/workspace \
lsp4j-mcp:local
Example MCP configuration:
{
"mcpServers": {
"java-lsp-docker": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--mount",
"type=bind,source=/absolute/path/to/java/project,target=/workspace",
"lsp4j-mcp:local"
]
}
}
}
The server uses stdio, so the image exposes no network port. Container logs are
written to stderr while stdout remains reserved for the MCP protocol. The image
runs as UID/GID 10001 by default and expects at least 1 GB of container memory.
Project Structure
LSP4J-MCP/
├── pom.xml # Maven build configuration
├── run.sh # Startup script
├── mcp-config.json # Example MCP configuration
├── src/
│ ├── main/
│ │ ├── java/com/devoxx/lsp4jmcp/
│ │ │ ├── client/
│ │ │ │ ├── JdtlsClient.java # LSP client for JDTLS
│ │ │ │ └── JdtlsLanguageClient.java # LSP callback handler
│ │ │ ├── tools/
│ │ │ │ └── JavaTools.java # Tool implementations
│ │ │ └── server/
│ │ │ └── McpServerMain.java # MCP server entry point
│ │ └── resources/
│ │ └── logback.xml # Logging configuration
│ └── test/
│ └── java/com/devoxx/lsp4jmcp/
│ ├── client/JdtlsClientTest.java
│ ├── tools/JavaToolsTest.java
│ └── server/McpServerMainTest.java
└── README.md
Testing
Run all tests:
mvn test
Dependencies
- LSP4J - Eclipse Language Server Protocol for Java
- MCP Java SDK - Model Context Protocol SDK
- JDTLS - Eclipse JDT Language Server
Example Prompts
Once the MCP server is configured, you can ask your AI assistant questions that will trigger the LSP tools. Here are some examples:
Finding Symbols
"Find all classes named Repository in this project"
"Search for methods containing 'save' in their name"
"Where is the UserService class defined?"
"List all interfaces in this codebase"
Finding References
"Find all usages of the
processOrdermethod at line 45 in OrderService.java"
"Where is the
CustomerRepositoryinterface used throughout the codebase?"
"Show me all places that call the constructor at line 12 of PaymentGateway.java"
Go to Definition
"What is the definition of the method being called at line 78, column 15 in CheckoutController.java?"
"Take me to the implementation of the interface method at line 23 in MyService.java"
Document Symbols
"List all methods and fields in the Customer.java file"
"What symbols are defined in src/main/java/com/example/service/OrderService.java?"
"Give me an overview of the structure of ConfigurationManager.java"
Finding Interface Methods
"Which interfaces define a method called 'findById'?"
"Find all classes that have a method named 'process'"
"Show me all interfaces containing the 'validate' method"
Complex Queries
"I need to understand how the
authenticatemethod works. First find its definition, then show me all places it's called."
"Refactor help: Find all usages of the deprecated
legacyProcessmethod so I can update them"
"I want to implement a new Repository interface. Show me all existing Repository interfaces and their methods."
Logging
Logs are written to the file specified by the LOG_FILE environment variable (default: /tmp/lsp4j-mcp.log).
Note: stdout is reserved for MCP protocol communication, so all logging goes to file.
Architecture
Claude Code ──MCP──▶ McpServerMain ──LSP4J──▶ JDTLS ──▶ Java Codebase
│
▼
JavaTools
(find_symbols, find_references, etc.)
The server:
- Starts JDTLS as a subprocess
- Connects via LSP4J (JSON-RPC over stdio)
- Exposes LSP features as MCP tools
- Communicates with Claude Code via MCP protocol
Examples using Claude Code
License
MIT
