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 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.