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

• 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 the source code of your dependencies or Gradle's own sources.
• 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 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

{
  "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:+"
      ]
    }
  }
}

See the documentation for more details.

Agent Skills

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

Included skills:

• running_gradle_builds: Running Gradle Commands, Background Jobs, and Investigating Failures.
• running_gradle_tests: Running and Investigating Tests.
• managing_gradle_dependencies: Auditing and updating dependencies.
• introspecting_gradle_projects: Mapping project structure, modules, and tasks.
• searching_dependency_sources: Searching and reading dependency source code.
• interacting_with_project_runtime: Running Code in the Project's Environment (REPL).
• researching_gradle_internals: Searching and reading the Gradle User Guide and source code.
• verifying_compose_ui: Visually verifying Compose UI components.
• gradle_expert: Senior Build Engineer guidance for build scripts and failures.

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

---

Troubleshooting & Notes

• Documentation Indexing: If you previously used the gradle_docs tool and want to see the new best-practices tag for existing Gradle versions, you must clear the documentation cache directory:
  • Windows: %USERPROFILE%\.gradle-mcp\cache\reading_gradle_docs
  • macOS/Linux: ~/.gradle-mcp/cache/reading_gradle_docs The server will automatically re-index the documentation on the next call.