# JavaLens

An MCP server that hands your agent 75 semantic Java tools built on Eclipse JDT: reference search, refactoring, type analysis. Useful when text search mixes up overloads and implementations.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 45
- Author: pzalutski-pixel
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pzalutski-pixel/javalens-mcp
- Updated: 2026-10-18
- HTML: https://affpapa.org/en/nevibecode/mcp/javalens

## What it does

JavaLens plugs into an agent as an MCP server and answers code questions through Eclipse JDT Core, the engine behind Eclipse IDE. That is where the accuracy comes from. It tells a field read apart from a field write, and locates casts, annotations, `catch` blocks, `instanceof` checks, method references and generic type arguments. Queries hit an index JDT builds when the project loads instead of walking source files.

The 75 tools cover symbol navigation, implementation lookup, refactoring such as rename and extract method, metrics including cyclomatic complexity, dead-code reachability, and the tests that transitively exercise a symbol. Source parsing spans Java 1.1 through 25, markdown Javadoc and compact source files included. Lombok members resolve too, because a bundled agent handles `@Data` accessors so they are not reported as undefined.

Java 21 or newer must sit on `PATH`, or `JAVA_HOME` must point at it. That applies to both install routes. Node.js 18+ matters only for the `npx` route; the release archive skips it. Project loading runs in the background, so the server answers right away while `health_check` reports progress. No Java 21 means no server, so check the version first.

One thing to watch: models lean toward `grep` and file reads even when semantic analysis wins. Put a note in `CLAUDE.md` telling the agent to reach for JavaLens tools on Java code.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `JAVA_PROJECT_PATH`, `JAVALENS_TIMEOUT_SECONDS`, `JAVALENS_LOG_LEVEL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env JAVA_PROJECT_PATH=<JAVA_PROJECT_PATH> --env JAVALENS_TIMEOUT_SECONDS=<JAVALENS_TIMEOUT_SECONDS> --env JAVALENS_LOG_LEVEL=<JAVALENS_LOG_LEVEL> --transport stdio javalens -- npx -y javalens-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add javalens --env JAVA_PROJECT_PATH=<JAVA_PROJECT_PATH> --env JAVALENS_TIMEOUT_SECONDS=<JAVALENS_TIMEOUT_SECONDS> --env JAVALENS_LOG_LEVEL=<JAVALENS_LOG_LEVEL> -- npx -y javalens-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "javalens": {
            "command": "npx",
            "args": [
                "-y",
                "javalens-mcp"
            ],
            "env": {
                "JAVA_PROJECT_PATH": "<JAVA_PROJECT_PATH>",
                "JAVALENS_TIMEOUT_SECONDS": "<JAVALENS_TIMEOUT_SECONDS>",
                "JAVALENS_LOG_LEVEL": "<JAVALENS_LOG_LEVEL>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "javalens": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "javalens-mcp"
            ],
            "env": {
                "JAVA_PROJECT_PATH": "<JAVA_PROJECT_PATH>",
                "JAVALENS_TIMEOUT_SECONDS": "<JAVALENS_TIMEOUT_SECONDS>",
                "JAVALENS_LOG_LEVEL": "<JAVALENS_LOG_LEVEL>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e JAVA_PROJECT_PATH=<JAVA_PROJECT_PATH> -e JAVALENS_TIMEOUT_SECONDS=<JAVALENS_TIMEOUT_SECONDS> -e JAVALENS_LOG_LEVEL=<JAVALENS_LOG_LEVEL> javalens npx -y javalens-mcp
```
Replace <…> with your own values

## When to use it
- find every call to a method without matching same-named methods elsewhere
- separate field writes from field reads
- list interface implementations rather than any mention of the type
- rename a symbol safely across the project
- measure cyclomatic complexity of a method

## Example prompts
- Use JavaLens to find every call to `UserService.save()` in this project
- Show me the implementations of `PaymentGateway` and where each one is used
- Rename `calcTotal` to `calculateTotal` across the whole project

## Similar
- [Serena MCP: the IDE for your agent](https://affpapa.org/en/nevibecode/mcp/serena-mcp-the-ide-for-your-agent.md) — MCP server · ★ 30677
- [Compiler Explorer](https://affpapa.org/en/nevibecode/mcp/compiler-explorer.md) — MCP server · ★ 19148
- [Claude Code Explorer MCP](https://affpapa.org/en/nevibecode/mcp/claude-code-explorer-mcp.md) — MCP server · ★ 6235
- [Tolgee](https://affpapa.org/en/nevibecode/mcp/tolgee.md) — MCP server · ★ 4139
- [jshookmcp](https://affpapa.org/en/nevibecode/mcp/jshookmcp.md) — MCP server · ★ 2061
- [pyscn](https://affpapa.org/en/nevibecode/mcp/pyscn.md) — MCP server · ★ 1096

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md