Skip to main content
Glama
Java Project Runner MCP

Java Project Runner MCP

Java Project Runner MCP (v1.3.1)

Single-process MCP server (stdio) that builds and manages registered Spring Boot + Maven projects on macOS, Linux, and Windows: list / inspect / build / start / stop / restart / status / logs / registry CRUD / reclaim.

Distributed via GitHub only (no npm publish). Prefer npx so clients fetch and build automatically.

Locked behavior

  • Start runs the configured JAR via java -jar — not spring-boot:run

  • Before start: Maven package (default) unless the JAR is fresher than pom.xml + src/** sources, or skipBuild is set; use rebuild: true to force package

  • Prefer ./mvnw when executable; otherwise system mvn

  • -DskipTests default on (configurable per call / registry)

  • Stop targets the managed process tree only (POSIX process group, or Windows taskkill /T) — never by port / main-class

  • Maven Wrapper: ./mvnw on Unix, mvnw.cmd / mvnw.bat on Windows; else system mvn

  • Registry: hand-edit ~/.java-project-runner/projects.json or use project_register / project_update / project_unregister

  • Same home by default: multiple MCP clients (e.g. Cursor + Claude Code) may share ~/.java-project-runner; mutating ops use per-project file locks (locks/<id>.lock) and return BUSY if contended

  • Optional JAVA_PROJECT_RUNNER_HOME (absolute path) overrides the data root if you need an isolated home

Requirements

  • Node.js 20+ (LTS)

  • macOS, Linux, or Windows

  • JDK + Maven (or project Maven Wrapper) for the projects you register

Related MCP server: erbina

Install

Cursor / Claude Code mcp.json — first launch downloads the repo and runs prepare → npm run build:

{
  "mcpServers": {
    "java-project-runner": {
      "command": "npx",
      "args": [
        "-y",
        "github:vinsmoke-sanji59/java-project-runner-mcp"
      ]
    }
  }
}

Requires Node.js 20+ on PATH. First run is slower; later runs use the npx cache.

Pin a tag/commit if you want a fixed version, e.g. github:vinsmoke-sanji59/java-project-runner-mcp#v1.3.1.

Optional: clone for development

git clone https://github.com/vinsmoke-sanji59/java-project-runner-mcp.git
cd java-project-runner-mcp
nvm use 20   # if you use nvm
npm install   # also runs prepare → build
npm test
npm run dev   # TypeScript via tsx

Or point MCP at a local build:

{
  "mcpServers": {
    "java-project-runner": {
      "command": "node",
      "args": ["/absolute/path/to/java-project-runner-mcp/dist/index.js"]
    }
  }
}

Registry

Create or edit ~/.java-project-runner/projects.json by hand, or use the register/update tools:

{
  "projects": [
    {
      "id": "order-service",
      "name": "Order Service",
      "path": "/Users/you/ws/order-service",
      "jarPath": "target/order-service-0.0.1-SNAPSHOT.jar",
      "javaHome": "/Library/Java/JavaVirtualMachines/temurin-21.jdk/Contents/Home",
      "skipTests": true,
      "defaultProfile": "local",
      "profiles": ["local", "dev"],
      "jvmArgs": ["-Xmx512m"],
      "healthCheckUrl": "http://127.0.0.1:8080/actuator/health",
      "stopTimeoutSeconds": 15,
      "enabled": true
    }
  ]
}

Notes:

  • id must be a single safe path segment: 1–64 chars, start/end alphanumeric; middle may include . _ -; no .. or path separators.

  • path must exist and contain pom.xml (enforced on register/update).

  • jarPath may be a concrete relative path or a single-glob filename such as target/*.jar (exactly one non-sources/javadoc match).

  • healthCheckUrl must be loopback (127.0.0.1 / localhost / ::1).

  • State / logs / locks live under ~/.java-project-runner/state/, logs/<id>/, and locks/<id>.lock (or under JAVA_PROJECT_RUNNER_HOME if set).

MCP tools

Tool

Purpose

project_list

List registered projects

project_inspect

pom / wrapper / jar resolvability / config

project_register

Add a project to the registry

project_update

Patch an existing project (id immutable)

project_unregister

Remove a project (refuses if running/unknown)

project_build

Maven build

project_start

Smart package → java -jar (rebuild / skipBuild optional)

project_stop

SIGTERM → wait → SIGKILL on managed pgid

project_force_stop

Fingerprint-gated stop; requires confirm: true; allowed for unknown

project_reclaim

Re-verify PID fingerprint after MCP restart

project_restart

stop then start under one lock

project_status

One or all runtime states

project_logs

Tail stdout/stderr (max 200 lines)

Start build flags

Flag

Effect

(none)

Skip Maven if resolved JAR mtime ≥ newest of pom.xml and src/** (.java/.xml/.yml/.yaml/.properties); else package

rebuild: true

Always Maven before start

skipBuild: true

Never Maven; JAR must already resolve

both true

INVALID_ARGS

Response includes buildSkipped and buildSkipReason (jar_fresh | skipBuild_flag | null).

Cursor / Claude Code config

Prefer the Install → Recommended npx block above in ~/.cursor/mcp.json or Claude Code .mcp.json.

Local clone / absolute node dist/index.js is fine for development. For local TypeScript iteration:

{
  "mcpServers": {
    "java-project-runner": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/java-project-runner-mcp/src/index.ts"
      ],
      "cwd": "/absolute/path/to/java-project-runner-mcp"
    }
  }
}

Safety

  • Only enabled registry projects can be built/started/stopped.

  • Paths are realpath-checked against the project root.

  • spawn(..., { shell: false }) only; goals / profiles / jvmArgs are whitelisted.

  • After MCP server restart, unverified PIDs become unknown (pid retained for reclaim/force_stop) — the server will not blind-kill them.

  • project_force_stop requires confirm: true and a matching java -jar cmdline fingerprint.

  • Multiple MCP clients may share the same home; overlapping ops on one project return BUSY instead of corrupting state.

License

MIT

Available Tools

13 tools
project_buildB

Run Maven build for a registered project (default goal package, -DskipTests by default)

Inputs: projectId (required), goal, profile, skipTests.

project_force_stopB

Stop a managed process when cmdline fingerprint still matches. Requires confirm:true. Allowed for unknown status; never blind-kills.

Inputs: confirm (required), projectId (required), timeoutSeconds.

project_inspectA

Inspect a registered project: pom/wrapper/javaHome/jarPath resolvability, Maven version probe, and config summary

Inputs: projectId (required).

project_listA

List registered Java/Spring Boot projects from ~/.java-project-runner/projects.json

Inputs: keyword.

project_logsC

Tail project logs (stdout/stderr/both), max 200 lines

Inputs: projectId (required), stream, tailLines.

project_reclaimC

Re-verify a persisted PID against the managed java -jar fingerprint and mark running if matched

Inputs: projectId (required).

project_registerC

Add a project to ~/.java-project-runner/projects.json (path must contain pom.xml)

Inputs: id (required), name (required), path (required), enabled (required), +9 more.

project_restartB

Stop (if running) then start under one project lock (same build skip / rebuild options as project_start)

Inputs: projectId (required), profile, rebuild, skipBuild.

project_startA

Start the configured JAR (detached process group). Builds with Maven unless the JAR is fresh or skipBuild is set; use rebuild to force package.

Inputs: projectId (required), profile, rebuild, skipBuild.

project_statusB

Query runtime status for one project or all tracked projects

Inputs: projectId.

project_stopB

Stop the managed process group only (SIGTERM then SIGKILL). Never kills by port/main-class.

Inputs: projectId (required), timeoutSeconds.

project_unregisterA

Remove a project from the registry. Refuses if runtime status is running/starting/stopping/unknown.

Inputs: projectId (required).

project_updateB

Patch an existing registry project (id cannot change). Re-validates the full entry.

Inputs: projectId (required), name, path, enabled, +9 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools target clearly distinct lifecycle operations (register/list/inspect/build/start/stop/restart/status/logs). The main possible confusion is between start and restart, and between stop and force_stop, but the descriptions make the distinctions explicit enough for an agent.

    Naming Consistency5/5

    Every tool follows the same project_<verb/action> snake_case convention, with predictable verb choices. There is no mixing of casing or naming styles.

    Tool Count5/5

    With 13 tools, the set is well-scoped for a Java project runner: registry management, build, runtime lifecycle, status, logs, and recovery operations each have a clear place. No tool appears redundant or excessive.

    Completeness5/5

    The surface covers the full lifecycle: register, list, inspect, update, unregister, build, start, stop, restart, status, logs, plus force-stop and PID reclaim recovery operations. No obvious operational dead ends remain for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables management of long-running development processes (such as dev servers, compilers, and watchers) from MCP hosts. Provides tools to start, stop, restart, check status, view logs, and send input to managed processes.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Bootstraps dev environments by installing, wiring, and verifying CLI tools and MCP servers from curated recipes, and provides scope-aware audit of MCP configurations.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      First-party MCP server and CLI for Xcode and iOS Simulator automation. Enables control of Xcode and iOS Simulator via MCP tools for tasks like building, testing, and automation.
      10 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables managing a local Minecraft hosting service through MCP, including server creation, start/stop, mod installation, and log retrieval.
      -