Gradle Optimization MCP Server

A Model Context Protocol (MCP) server that gives Claude direct, structured access to your Gradle build — dependency graphs, build scans, cache health, test results, and more — without you pasting logs by hand.

About
Features
Tech Stack
Prerequisites
Install
Configuration
Usage
Development
Releases
Troubleshooting
Contributing
License

About

Diagnosing a slow or broken Gradle build usually means running a command, copying its output, and pasting it into a chat. This server removes that step: it speaks MCP over stdio, so Claude can call Gradle tools directly — inspect dependency insight, run a dry-run analysis, profile cache invalidation, or pull a test summary — and reason over structured results instead of raw console text.

Features

Tool	What it does
`analyze_build_dry_run`	Analyzes a `--dry-run` task graph without executing the build
`check_project_isolation_violations`	Flags cross-project state access that breaks Project Isolation
`get_dependency_insight`	Explains why a dependency resolved to a given version
`audit_configuration_cache_inputs`	Audits what invalidates the configuration cache
`verify_dependency_metadata`	Static audit of verification-metadata.xml (checksums / trusted overrides)
`lint_gradle_plugins`	Lints applied Gradle plugins for known issues
`analyze_build_scan`	Analyzes a Gradle Build Scan
`inspect_declarative_schemas`	Inspects declarative Gradle DSL schemas
`profile_cache_invalidation_timeline`	Profiles build/configuration cache invalidation over time
`analyze_parallelization_bottlenecks`	Dry-run parallelism heuristics (histograms + capped candidates)
`gradle_health`	Reports project health (modules, versions, structure)
`gradle_run` / `gradle_run_log`	Runs a Gradle task and retrieves its log
`gradle_test_summary`	Summarizes test results for a run
`gradle_deps`	Renders the resolved dependency graph

Tech Stack

Language: Kotlin 2.4.10 (Multiplatform, JVM target)
Build: Gradle 9.6.1
Runtime: Ktor server core/Netty, Koin DI (compiler-plugin annotations)
Protocol: Model Context Protocol Kotlin SDK, stdio transport
CI/CD: GitHub Actions (trunk-based CI + tag-triggered releases), git-cliff for release notes

Prerequisites

Requirement	Minimum Version	Notes
JDK	21	Required to run the fat jar and to build the project
Gradle	9.6.1	Only needed if building from source. The wrapper (`./gradlew`) handles this
An MCP-capable client	—	e.g. Claude Desktop or Claude Code

Install

Option A — download a release (recommended):

gh release download --repo JosephSanjaya/gradle-opt-mcp --pattern '*.jar'
java -jar gradle-opt-mcp-*.jar

The process blocks waiting for stdio input — that's expected. It only responds when an MCP client connects.

Option B — build from source:

git clone https://github.com/JosephSanjaya/gradle-opt-mcp.git
cd gradle-opt-mcp
./gradlew :server:fatJar
java -jar server/build/libs/*-all.jar

Configuration

The server reads these environment variables at startup:

Variable	Default	Description
`GRADLE_PROJECT_DIR`	current working directory	Absolute path to the Gradle project the tools should analyze
`GRADLE_VARIANT`	none	Build variant/flavor passed to tools that need one (e.g. Android product flavors)

Set these in your MCP client config, not as global exports — each project you analyze needs its own value.

Usage

Add the server to your MCP client config, pointing args at the downloaded/built jar and GRADLE_PROJECT_DIR at the project you want Claude to inspect:

{
  "mcpServers": {
    "gradle-optimization": {
      "command": "java",
      "args": ["-jar", "/absolute/path/to/gradle-opt-mcp-1.0.0.jar"],
      "env": {
        "GRADLE_PROJECT_DIR": "/absolute/path/to/your/gradle/project"
      }
    }
  }
}

Restart your MCP client, then ask Claude something like "check this project's Gradle health" or "why did com.google.guava:guava resolve to this version?" — Claude calls the matching tool and reasons over the structured result.

Development

Intent	Command
Compile	`./gradlew compileKotlin`
Build server distribution	`./gradlew :server:installDist`
Build fat jar	`./gradlew :server:fatJar`
Lint & auto-format	`./gradlew detekt`
Run all tests	`./gradlew test`

Releases

This project is trunk-based: main is always releasable, there are no long-lived branches. Every push to main and every PR runs CI (detekt + test, plus a Conventional Commits check on PRs).

To cut a release, push a tag matching vX.Y.Z (optionally -alpha/-beta/-rc) from a commit on main. The release workflow then:

Verifies the tag's commit is reachable from origin/main
Builds the fat jar with the tag as its version
Generates a SHA-256 checksum for the jar
Generates release notes from commit history with git-cliff
Publishes a GitHub Release with the jar, checksum, and notes attached

Troubleshooting

java.lang.UnsupportedClassVersionError
Cause: running the jar with a JDK older than 21.
Fix: install JDK 21+ (e.g. Temurin) and confirm with java -version.

Claude/your MCP client shows the server as unavailable or with no tools
Cause: the args path in your MCP config doesn't point at a real jar file, or GRADLE_PROJECT_DIR doesn't exist.
Fix: run java -jar <path> manually from a terminal — if it starts without printing an error and just sits idle, the jar is fine and the issue is the client config path.

A Gradle-backed tool call fails or times out
Cause: GRADLE_PROJECT_DIR points at a directory with no Gradle wrapper (no gradlew), or the target project itself fails to configure.
Fix: point GRADLE_PROJECT_DIR at the project root containing gradlew, and confirm that project builds standalone first.

Contributing

Fork the repo and branch off main
Make focused, independently-compiling commits — every commit must pass ./gradlew detekt test
Follow Conventional Commits: feat, fix, chore, refactor, docs, test, perf, build, ci
Open a PR into main — CI enforces the commit format and runs the full build

License

No license file is published in this repository yet. Until one is added, all rights are reserved by the author.

gradle-opt-mcp