Gradle MCP server

A Model Context Protocol (MCP) server for Gradle. It gives AI agents the tools they need to explore project structures, run tasks, audit dependencies, and interact with the JVM runtime.

Features

Source downloading and indexing tools will be moving to a dedicated MCP/cli soon.

• Agent Skills: Built-in workflows that guide AI agents through complex Gradle tasks. See the documentation for more.
• Project Mapping: Easily explore multi-project structures, modules, tasks, and properties.
• Smart Task Execution: Run builds in the background, monitor progress, and capture specific task outputs without the noise. Supports advanced environment control and shell environment sourcing.
• Advanced Testing: Run filtered test suites and get full access to logs and stack traces for every test case.
• Dependency & Source Search: Search Maven Central and browse dependency, JDK standard library, and Gradle source code.
• Interactive Kotlin REPL: Test project utilities and explore APIs in a persistent REPL with access to all your classes.
• Compose UI Previews: Render UI components directly to images from the project runtime for visual auditing.
• Gradle Documentation: Instant access to searchable, indexed Gradle User Guides and DSL references.
• Develocity Build Scans: One-click publishing of Build Scans for deep troubleshooting.
• Token Optimized: Compact data formats designed to keep context usage low.

Installation

JDK Requirement

JDK 21 or higher is required to run gradle-mcp. You can use JBang to install JDKs too: docs.

Use jbang:

# For releases
jbang run --quiet --fresh gradle-mcp@rnett

# For snapshots
jbang run --quiet --fresh gradle-mcp-snapshot@rnett

Alternatively, run the GAV directly:

# For releases
jbang run --fresh dev.rnett.gradle-mcp:gradle-mcp:+

# For snapshots
jbang run --fresh \
  --repos snapshots=https://central.sonatype.com/repository/maven-snapshots/ \
  dev.rnett.gradle-mcp:gradle-mcp:+

You can add an alias to make invoking it easier:

jbang alias add dev.rnett.gradle-mcp:gradle-mcp:+

Then run it with jbang --fresh gradle-mcp.

Or even install it as a command (gradle-mcp):

jbang app setup
jbang app install --name gradle-mcp dev.rnett.gradle-mcp:gradle-mcp:+

See jbang documentation for more details.

Example MCP configuration

{
  "mcpServers": {
    "gradle": {
      "command": "jbang",
      "args": [
        "run",
        "--quiet",
        "--fresh",
        "gradle-mcp@rnett"
      ]
    }
  }
}

{
  "mcpServers": {
    "gradle": {
      "command": "bash -c",
      "args": [
        "jbang run --quiet --fresh gradle-mcp@rnett"
      ]
    }
  }
}

CDS Issues

If you experience errors related to CDS (Class Data Sharing), typically caused by native JVMTI agents from security software (e.g., SentinelOne), you can disable it by adding --no-cds to the jbang command.

The GRADLE_MCP_PROJECT_ROOT environment variable can provide the default Gradle project root when a tool call omits projectRoot.

Usage

Run the server. By default it runs in STDIO mode. You can use the server argument to run it as a server on port 47813.

Agent Skills

Agent Skills are specialized guides that help AI agents navigate common Gradle workflows reliably.

Included skills:

• using-gradle: Inspect, run, and diagnose existing Gradle builds — project mapping, test diagnostics, dependency auditing, and source research.
• authoring-gradle-builds: Modify build definitions, wiring, and project structure — dependency declarations, module creation, toolchain configuration, and best practices.
• advanced-gradle-dependencies: Diagnose and resolve complex dependency issues involving variants, capabilities, verification, and repository governance.
• interacting-with-project-runtime: Execute and verify project logic in real-time using a persistent Kotlin REPL with full classpath access.
• verifying-compose-ui: Visually audit Compose UI components by rendering them to images from the project runtime.

For instructions on how to use these skills, see the Agent Skills documentation.

Danger

DO NOT EVER EXPOSE THIS SERVER TO THE INTERNET.

Publishing Build Scans

Even if you don't have your build configured to publish build scans automatically, you can still publish build scans - just ask your agent to publish a scan when invoking Gradle. These will publish to the public https://scans.gradle.com instance unless you have a Develocity instance configured in your build.