Gradle

You run a Gradle MCP Server to connect an AI assistant to your Gradle projects. It automatically detects Gradle workspaces, lets you start and monitor builds in real time, and exposes a stable, LLM-friendly interface for managing tasks, daemons, and logs from a dashboard and via MCP client integrations.

How to use

You interact with the Gradle MCP Server through an MCP client. First, start the server, then configure your client to point at it. Your AI assistant can discover projects, list tasks, run one or more tasks with extra arguments, check and manage the Gradle daemon, and view real-time build logs. Use the server to perform actions like building modules, running tests, or inspecting daemon health, and rely on structured error output to understand failures.

How to install

Prerequisites you need before installing the server are a Python 3.10+ runtime and a Gradle project that already includes a wrapper (gradlew/gradlew.bat). You will also use the uv tooling and a Python package installation method to run the MCP server locally.

git clone https://github.com/jermeyyy/gradle-mcp.git
cd gradle-mcp

# Install using uv (recommended)
uv sync

# Or install in editable mode with Python
pip install -e .

Configure your MCP client

Add the server to your MCP client configuration so your AI assistant can connect and start issuing Gradle commands. The example shows how a client might reference the server using the uv runner.

{
  "mcpServers": {
    "gradle": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/gradle-mcp/installation",
        "gradle-mcp"
      ],
      "env": {
        "GRADLE_PROJECT_ROOT": "/path/to/your/gradle/project"
      }
    }
  }
}

Start using the MCP server

From your Gradle project directory, start the MCP server. The server will auto-detect the Gradle wrapper in the current directory and expose a web dashboard for monitoring at the default URL.

# Navigate to your Gradle project directory
cd /path/to/your/gradle/project

# Start the MCP server
uv run gradle-mcp

The dashboard is available at http://localhost:3333 and will show daemon status, active builds, and real-time logs.

## Interact with the server from an AI assistant

Your assistant can list projects, enumerate tasks, run tasks with arguments, manage daemons, and inspect Gradle configuration. Use the following common actions to guide build automation.

Examples of supported actions include building modules, running tests with exclusions, listing tasks, and checking daemon health.

## Available tools

### list\_projects

Discover all Gradle projects in the workspace and return a structured list with name, path, and description.

### list\_project\_tasks

List available tasks for a specific project, optionally filtered by group and whether to include descriptions.

### run\_task

Execute one or more Gradle tasks with optional additional arguments and return a TaskResult indicating success, errors, and structured error details.

### clean

Clean build artifacts for a project using the dedicated cleaning tool to avoid unsafe deletions.

### daemon\_status

Query the status of all Gradle daemons and return current runtime information.

### stop\_daemon

Stop all Gradle daemons to reclaim memory or resolve daemon issues.

### get\_gradle\_config

Retrieve the current Gradle configuration including memory settings and wrapper details.