junit-mcp-server

An MCP (Model Context Protocol) server that exposes JUnit test discovery and execution as tools, allowing AI coding agents to run tests directly without relying on shell commands.

Why

When an LLM needs to run tests today, it typically shells out to mvn test or ./gradlew test, captures the raw terminal output, parses it as plain text, and forwards that interpretation to the user. This approach has three problems: the output is verbose and wastes tokens, text parsing is fragile and error-prone, and the result leaves room for misinterpretation.

junit-mcp-server connects the LLM directly to the JUnit Platform API instead of going through the command line. Test results come back as structured JSON with exact pass/fail counts, failure causes, and stack traces — nothing more.

The benefits:

• Fewer tokens consumed — the agent receives only the data it needs, not pages of build logs
• More precise responses — structured output leaves no room for parsing ambiguity or misreading
• No dependency on build tool output format — works regardless of how Gradle or Maven formats its console output

How it works

On startup the server detects the build tool (Gradle or Maven), extracts the full testRuntimeClasspath by invoking the build tool once, loads everything into a URLClassLoader, and registers MCP tools backed by the JUnit Platform Launcher API.

The agent never needs to call gradle test or mvn test — it calls the MCP tools instead.

Check the ARCHITECTURE.md for more.

Requirements

• Java 21+
• The target project must be pre-compiled before starting the server (./gradlew testClasses or mvn test-compile)

Build

mvn package

This produces a fat/shaded jar at target/junit-mcp-server-1.0-SNAPSHOT.jar.

Available tools

All run tools return a JSON report:

[{
  "className": "com.example.CalculatorTest",
  "total": 3,
  "passed": 2,
  "failed": 1,
  "skipped": 0,
  "tests": [
    { "name": "shouldAdd", "status": "passed" },
    { "name": "shouldSubtract", "status": "passed" },
    { "name": "shouldDivide", "status": "failed", "failure": { "cause": "/ by zero", "stackTrace": "..." } }
  ]
}]

Configuration

Replace /absolute/path/to/your/project with the actual path to the Gradle or Maven project you want the agent to test, and /absolute/path/to/junit-mcp-server.jar with the path to the built jar.

Claude Code (CLI)

Add to your project's .claude/mcp.json or to the global ~/.claude/mcp.json:

{
  "mcpServers": {
    "junit": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/junit-mcp-server-1.0-SNAPSHOT.jar",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

Or via the CLI:

claude mcp add junit -- java -jar /absolute/path/to/junit-mcp-server-1.0-SNAPSHOT.jar /absolute/path/to/your/project

Claude Desktop (claude.ai)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "junit": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/junit-mcp-server-1.0-SNAPSHOT.jar",
        "/absolute/path/to/your/project"
      ]
    }
  }
}

Cursor

Open Settings → MCP and add a new server entry, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "junit": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/

... [View full README on GitHub](https://github.com/clarenced/junit-mcp-server#readme)