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.
• 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 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: Ask your agent to publishing of Build Scans for deep troubleshooting.
• Token Optimized: Compact data formats designed to keep context usage low.

Configuration

The GRADLE_MCP_PROJECT_ROOT environment variable can be set to provide a default Gradle project root. This is used if no project root is specified in a tool call and there isn't exactly one MCP root configured.

Getting started

[!IMPORTANT] JDK 25 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

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

Alternatively, run the GAV directly:

jbang run --fresh dev.rnett.gradle-mcp:gradle-mcp:+

{
  "mcpServers": {
    "gradle": {
      "command": "jbang",
      "args": [
        "run",
        "--fresh",
        "dev.rnett.gradle-mcp:gradle-mcp:+"
      ]
    }
  }
}

[!TIP] 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. See the documentation for more details.

Agent Skills

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

Included skills:

• gradle: Running builds, tests, introspecting projects, creating modules, and diagnosing failures.
• exploring_dependency_sources: Searching and reading dependency, plugin, and Gradle internal source code.
• managing_gradle_dependencies: Auditing, updating, and adding dependencies.
• interacting_with_project_runtime: Running Code in the Project's Environment (REPL).
• verifying_compose_ui: Visually verifying Compose UI components.

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