Gradle MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with Gradle projects using the Gradle Wrapper.

Features

• list_projects - List all Gradle projects in the workspace

• list_project_tasks - List available tasks for a specific project

• run_task - Execute Gradle tasks (build, test, assemble, etc.)

• clean - Clean build artifacts (separate from run_task for safety)

Installation

Requirements

• Python 3.10+

• FastMCP 2.0+

• Gradle project with wrapper (gradlew)

Install

Usage

Start the Server

Logging

The server uses FastMCP's built-in logging mechanism to send log messages back to MCP clients:

• Tool invocations - Logs when each tool is called with its parameters

• Gradle output - Debug-level logs of full stdout/stderr from Gradle task execution

• Operation progress - Info messages about projects found, tasks discovered, etc.

• Success/errors - Completion status and error details with structured data

Log levels used:

• DEBUG - Gradle stdout/stderr output (full build logs)

• INFO - Normal operations (tool calls, results, progress)

• ERROR - Task failures with error details

Client handling:

• Logs are sent through the MCP protocol to the client

• How clients display these logs depends on their implementation

• Development clients may show logs in real-time

Progress Reporting

The server provides real-time progress updates when executing Gradle tasks:

• Real-time parsing - Parses Gradle wrapper output to extract actual progress percentages

• Progress patterns - Looks for patterns like <============-> 93% EXECUTING [19s] in Gradle output

• MCP protocol - Uses FastMCP's ctx.report_progress() to send updates via MCP protocol

• Client display - Clients can show live progress bars or percentage updates

How it works:

1. Gradle tasks run without -q (quiet) flag to output progress information

2. Server reads Gradle output line-by-line in real-time using subprocess.Popen()

3. Regex pattern r'(\d+)%' extracts percentage from lines containing progress indicators

4. Progress updates are sent asynchronously via await ctx.report_progress(progress, total=100)

5. Clients receive these updates and can display them to users

Applies to:

• run_task - Shows progress for any Gradle task execution

• clean - Shows progress for cleaning operations

Error Reporting

When Gradle tasks fail, the server provides comprehensive error messages:

• Intelligent parsing - Backward search strategy to find actual error details:

  1. Combines stdout and stderr - Gradle splits output (task failures → stdout, summaries → stderr)

  2. Locates FAILURE: or BUILD FAILED markers in combined output

  3. Searches backwards from these markers to find the first failed task

  4. Captures everything from the first failed task onwards (all failures, violations, and summaries)

• Complete error details - Captures all error messages from multiple failed tasks with their specific violations

• Smart fallback - If no task failures found, includes up to 100 lines before BUILD FAILED for maximum context

• Structured output - Returns both the parsed error message and full stdout/stderr for debugging

How it works:

• Gradle outputs task execution and error details to stdout (e.g., > Task :app:detekt FAILED + violations)

• Gradle outputs failure summaries to stderr (e.g., FAILURE: Build completed with 2 failures)

• The parser combines both streams and searches backwards from summary markers to find all task failures

• This ensures all error details (detekt violations, compilation errors, test failures) are captured

Error message examples:

For multiple linting/analysis failures (detekt, ktlint, etc.):

For compilation failures:

The error field contains the most relevant failure information starting from where the actual errors occur, while stdout and stderr contain complete logs (also sent via DEBUG logging).

• See your MCP client's documentation for log viewing

• Enable debug logging in your client to see Gradle output

Environment Variables

• GRADLE_PROJECT_ROOT - Path to Gradle project (default: current directory)

• GRADLE_WRAPPER - Path to gradlew script (default: auto-detected)

MCP Tools

list_projects()

List all Gradle projects in the workspace.

Returns: List of projects with name and path

list_project_tasks(project: str | None)

List tasks for a specific project.

Parameters:

• project - Project path (e.g., :app, or : / None / "" for root)

Returns: List of tasks with name, description, and group

run_task(task: str, args: list[str] | None)

Run a Gradle task. Cannot run cleaning tasks (use clean tool instead).

Parameters:

• task - Task name with optional project path (e.g., :app:build, build)

• args - Additional Gradle arguments (e.g., ["-x", "test"])

Returns: Success status and error message if failed

clean(project: str | None)

Clean build artifacts for a project.

Parameters:

• project - Project path (e.g., :app, or : / None / "" for root)

Returns: Success status and error message if failed

Examples

Using with MCP Client

As Python Module

Development

Architecture

Safety Design

• run_task blocks cleaning tasks (clean, cleanBuild, etc.)

• clean tool is the only way to run cleaning operations

• Prevents accidental cleanup during build operations

Task Execution

• Uses Gradle wrapper for compatibility

• -q flag for quiet output (errors only)

• --no-build-cache for clean execution

• Progress reporting via FastMCP context

License

[Add your license here]

Code Quality

Running Tests

Project Structure

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.