Java Project Runner MCP
Builds and manages registered Spring Boot + Maven projects on macOS, including project listing/inspection, Maven packaging, starting JARs via java -jar, stopping/restarting, status checks, log tailing, and registry management.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Java Project Runner MCP start order-service and show its recent logs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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— notspring-boot:runBefore start: Maven
package(default) unless the JAR is fresher thanpom.xml+src/**sources, orskipBuildis set; userebuild: trueto force packagePrefer
./mvnwwhen executable; otherwise systemmvn-DskipTestsdefault on (configurable per call / registry)Stop targets the managed process tree only (POSIX process group, or Windows
taskkill /T) — never by port / main-classMaven Wrapper:
./mvnwon Unix,mvnw.cmd/mvnw.baton Windows; else systemmvnRegistry: hand-edit
~/.java-project-runner/projects.jsonor useproject_register/project_update/project_unregisterSame 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 returnBUSYif contendedOptional
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
Recommended: npx from GitHub (no local clone)
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 tsxOr 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:
idmust be a single safe path segment: 1–64 chars, start/end alphanumeric; middle may include._-; no..or path separators.pathmust exist and containpom.xml(enforced on register/update).jarPathmay be a concrete relative path or a single-glob filename such astarget/*.jar(exactly one non-sources/javadocmatch).healthCheckUrlmust be loopback (127.0.0.1/localhost/::1).State / logs / locks live under
~/.java-project-runner/state/,logs/<id>/, andlocks/<id>.lock(or underJAVA_PROJECT_RUNNER_HOMEif set).
MCP tools
Tool | Purpose |
| List registered projects |
| pom / wrapper / jar resolvability / config |
| Add a project to the registry |
| Patch an existing project (id immutable) |
| Remove a project (refuses if running/unknown) |
| Maven build |
| Smart package → |
| SIGTERM → wait → SIGKILL on managed pgid |
| Fingerprint-gated stop; requires |
| Re-verify PID fingerprint after MCP restart |
| stop then start under one lock |
| One or all runtime states |
| Tail stdout/stderr (max 200 lines) |
Start build flags
Flag | Effect |
(none) | Skip Maven if resolved JAR mtime ≥ newest of |
| Always Maven before start |
| Never Maven; JAR must already resolve |
both true |
|
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
enabledregistry projects can be built/started/stopped.Paths are realpath-checked against the project root.
spawn(..., { shell: false })only; goals / profiles /jvmArgsare whitelisted.After MCP server restart, unverified PIDs become
unknown(pid retained for reclaim/force_stop) — the server will not blind-kill them.project_force_stoprequiresconfirm: trueand a matchingjava -jarcmdline fingerprint.Multiple MCP clients may share the same home; overlapping ops on one project return
BUSYinstead of corrupting state.
License
MIT
Available Tools
13 toolsproject_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
Scored across 13 tools
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.
Every tool follows the same project_<verb/action> snake_case convention, with predictable verb choices. There is no mixing of casing or naming styles.
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.
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
Related MCP Connectors
Create, deploy, and operate MCP servers directly from your GitHub repositories.
A MCP server built for developers enabling Git based project management with project and personal…
Access all your MCPBundles tools in one place. Unified hub for all enabled bundles.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseNot gradedqualityBmaintenanceBootstraps 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
- AlicenseNot gradedqualityCmaintenanceFirst-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 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnables managing a local Minecraft hosting service through MCP, including server creation, start/stop, mod installation, and log retrieval.-