Gradle

You set up a Gradle MCP Server to query Gradle project details, run tasks, and execute tests from AI tools or editors. It connects to Gradle projects via the Gradle Tooling API, returning structured information and formatted outputs you can easily consume in your workflow.

How to use

You connect an MCP client (such as an IDE extension or an AI assistant) to the Gradle MCP Server to perform common Gradle operations. You can request detailed project information, execute build tasks, and run tests with hierarchical results. The server returns structured data for project inspection, textual execution outputs for tasks, and a hierarchical test tree showing suites, classes, and tests with outcomes and failure messages when applicable.

How to install

Prerequisites: ensure you have Java 17 or newer installed. On your development machine, you also need curl for Unix-like systems or PowerShell for Windows to download the server package.

Steps for Linux/macOS

# Linux / macOS (requires curl)
TARGET_DIR="$HOME/mcp-servers/gradle-mcp-server"; mkdir -p "$TARGET_DIR"; curl -fSL -o "$TARGET_DIR/gradle-mcp-server-all.jar" "https://github.com/IlyaGulya/gradle-mcp-server/releases/latest/download/gradle-mcp-server-all.jar" && echo "Downloaded to '$TARGET_DIR'." || echo "Download failed."

Steps for Windows

# Windows (PowerShell 5+)
$targetDir = Join-Path $env:USERPROFILE "mcp-servers\gradle-mcp-server"; if (-not (Test-Path $targetDir)) { New-Item -ItemType Directory -Path $targetDir -Force | Out-Null }
$outFile = Join-Path $targetDir "gradle-mcp-server-all.jar"; Write-Host "Downloading..."; Invoke-WebRequest -Uri "https://github.com/IlyaGulya/gradle-mcp-server/releases/latest/download/gradle-mcp-server-all.jar" -OutFile $outFile -ErrorAction Stop; Write-Host "Downloaded to '$targetDir'."

Manual download

If you prefer manual download, save the JAR to a stable location you control. Typical locations are shown for reference, but use your chosen path.

# Example destination (adjust as needed)
# macOS/Linux: ~/mcp-servers/gradle-mcp-server/
# Windows: %USERPROFILE%\mcp-servers\gradle-mcp-server\

Configure a client to use the server

Once the server JAR is downloaded, you configure your MCP client to run the server via stdio. You provide the absolute path to the JAR in the client configuration.

{
  "mcpServers": {
    "gradle_mcp": {
      "command": "java",
      "args": [
        "-jar",
        "<absolute_path_to_home>/mcp-servers/gradle-mcp-server/gradle-mcp-server-all.jar"
      ],
      "env": {},
      "disabled": false,
      "autoApprove": []
    }
  }
}

Start the server (runtime example)

Start the server by running the JAR with Java. The server communicates over stdio by default and starts on demand when a client connects.

java -jar <path_to_your_jar>/gradle-mcp-server-all.jar

Configuration (command-line options)

You can control the server behavior with command-line options when launching the JAR. Use stdio by default. To run as an SSE server on a port, specify --sse and optionally the port number. You can enable verbose logging with --debug.

java -jar gradle-mcp-server-all.jar --stdio
java -jar gradle-mcp-server-all.jar --sse 8080
java -jar gradle-mcp-server-all.jar --sse --debug

Available tools

get_gradle_project_info

Retrieves detailed information about a Gradle project, with optional categories such as buildStructure, tasks, environment, and projectDetails. Returns a structured JSON object.

execute_gradle_task

Executes specified Gradle tasks (e.g., build, clean) and returns a formatted text output including stdout and stderr along with a final status.

run_gradle_tests

Runs Gradle test tasks and returns results in a hierarchical JSON tree (Suite -> Class -> Test) with outcomes, failure messages, and adjustable output capture.