What can you do with this server?

The Gradle MCP Server enables AI assistants to build, test, and manage Gradle projects through automated execution, real-time monitoring, and configuration management. **Core Capabilities:** * **Project & Task Management**: Discover all Gradle projects in the workspace, list available tasks with optional filtering by group and descriptions, and execute single or multiple tasks with full argument support using standard Gradle path notation (e.g., ':app:build') * **Safe Build Operations**: Run any Gradle task while protecting against accidental deletion through a dedicated clean tool for removing build artifacts * **Daemon Control**: Monitor running Gradle daemons (PID, status, memory usage) and stop daemons to free resources or resolve issues * **Configuration Inspection**: View detailed Gradle settings including JVM arguments, memory configuration, daemon status, parallel execution, caching, maximum worker count, distribution URL, and version information * **Real-Time Monitoring**: Access a web dashboard at localhost:3333 for live build progress, daemon status, active builds, and searchable build logs with WebSocket updates * **Structured Error Reporting**: Receive LLM-optimized error responses with concise summaries, failed task details, and deduplicated compilation errors with clean file paths * **Environment Configuration**: Customize behavior through environment variables for project root, wrapper location, and JVM options **Use Cases:** Building and testing projects conversationally, troubleshooting build failures with structured analysis, managing dependencies and configurations, monitoring build performance and daemon health, and automating development workflows.

Which integrations are available for this server?

Provides tools for interacting with [Gradle](/mcp/servers/integrations/gradle) projects, including listing projects and tasks, executing build tasks, running tests, and cleaning build artifacts through the Gradle Wrapper.

Gradle MCP Server

A Model Context Protocol (MCP) server for seamless Gradle integration with AI assistants

Python 3.10+ License: MIT FastMCP 2.0+

Empower your AI coding assistant to build, test, and manage Gradle projects with real-time monitoring

Features • Installation • Quick Start • Web Dashboard • API Reference • Contributing

✨ Features

🛠️ Build Automation

Project Discovery — Automatically detect and list all Gradle projects in your workspace
Task Management — Browse and execute any Gradle task with full argument support
Multi-Task Execution — Run multiple tasks in a single command
Safe Cleaning — Dedicated clean tool prevents accidental artifact deletion

📊 Real-Time Monitoring

Live Progress Tracking — Visual progress updates during task execution
Web Dashboard — Browser-based monitoring with WebSocket updates
Daemon Management — Monitor and control Gradle daemon processes
Build Logs — Searchable, real-time build log viewer

🔧 Configuration & Diagnostics

Config Inspection — View JVM args, daemon settings, and Gradle version
Memory Monitoring — Track daemon memory usage and health
Structured Error Output — LLM-friendly error responses with deduplicated compilation errors and task failure summaries

📸 Web Dashboard

The Gradle MCP Server includes a powerful web dashboard for real-time build monitoring. The dashboard starts automatically when the server runs and is accessible at http://localhost:3333.

Dashboard Overview

The main dashboard provides:

Daemon Status — Real-time view of running Gradle daemons with PID, status, and memory usage
Active Builds — Live tracking of currently executing tasks
Quick Actions — One-click daemon management (stop all, refresh status)
Auto-Refresh — WebSocket-powered updates without manual refresh

Build Logs Viewer

The logs viewer offers:

Real-Time Streaming — Watch build output as it happens
Log Filtering — Search and filter through build history
Clear Logs — One-click log clearing for fresh sessions
Persistent History — Logs persist across page refreshes during a session

📦 Installation

Requirements

Python 3.10+
Gradle project with wrapper (gradlew / gradlew.bat)
MCP-compatible client (e.g., Claude Desktop, Cursor, VS Code with Copilot)

Install from Source

git clone https://github.com/jermeyyy/gradle-mcp.git cd gradle-mcp # Using uv (recommended) uv sync # Or using pip pip install -e .

🚀 Quick Start

1. Start the Server

# Navigate to your Gradle project directory cd /path/to/your/gradle/project # Start the MCP server uv run gradle-mcp

The server will:

Auto-detect the Gradle wrapper in the current directory
Start the web dashboard at http://localhost:3333 (or higher if port already occupied)
Begin listening for MCP client connections

2. Configure Your MCP Client

Add the server to your MCP client configuration. For example, in Claude Desktop's claude_desktop_config.json:

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

3. Start Building!

Your AI assistant can now execute Gradle commands:

"Build the app module" "Run all tests except integration tests" "Show me the available tasks for the core module" "Check the Gradle daemon status"

🔧 Configuration

Environment Variables

Variable	Description	Default
`GRADLE_PROJECT_ROOT`	Root directory of the Gradle project	Current directory
`GRADLE_WRAPPER`	Path to Gradle wrapper script	Auto-detected
`GRADLE_OPTS`	JVM options for Gradle client	—
`JAVA_OPTS`	General Java options	—

Example Configuration

# Custom project location export GRADLE_PROJECT_ROOT=/path/to/project uv run gradle-mcp # Custom wrapper location export GRADLE_WRAPPER=/path/to/custom/gradlew uv run gradle-mcp

📚 MCP Tools API

Project & Task Management

`list_projects()`

List all Gradle projects in the workspace.

Returns: List of projects with name, path, and description

`list_project_tasks(project, include_descriptions, group)`

List available tasks for a project, optionally filtered by group.

Parameter	Type	Description
`project`	`str \| None`	Project path (e.g., `:app`). Use `None`, `""`, or `:` for root
`include_descriptions`	`bool`	Include task descriptions (default: `False`)
`group`	`str \| None`	Filter by task group (e.g., `Build`, `Verification`)

Returns: Grouped list of tasks

`run_task(task, args)`

Execute one or more Gradle tasks.

Parameter	Type	Description
`task`	`str \| list[str]`	Task(s) to run. Examples: `build`, `:app:build`, `[':core:build', ':app:assemble']`
`args`	`list[str] \| None`	Additional Gradle arguments (e.g., `['--info', '-x', 'test']`)

Returns: TaskResult with:

success: bool — Whether the task completed successfully
error: ErrorInfo | None — Structured error information (see Structured Error Output)

⚠️ Note: Cleaning tasks are blocked — use the clean tool instead.

`clean(project)`

Clean build artifacts for a project.

Parameter	Type	Description
`project`	`str \| None`	Project path (e.g., `:app`). Use `None`, `""`, or `:` for root

Returns: TaskResult with:

success: bool — Whether clean completed successfully
error: ErrorInfo | None — Structured error information (see Structured Error Output)

Daemon Management

`daemon_status()`

Get status of all running Gradle daemons.

Returns: Running status, list of daemon info (PID, status, memory), and any errors

`stop_daemon()`

Stop all Gradle daemons. Useful for freeing memory or resolving daemon issues.

Returns: Success status and error message if failed

Configuration

`get_gradle_config()`

Get current Gradle configuration including memory settings.

Returns: Configuration object with:

jvm_args — JVM arguments from gradle.properties
daemon_enabled — Whether daemon is enabled
parallel_enabled — Whether parallel execution is enabled
caching_enabled — Whether build caching is enabled
max_workers — Maximum worker count
distribution_url — Gradle distribution URL
gradle_version — Gradle version

💡 Usage Examples

With MCP Client

# Discover projects list_projects() # List build tasks for a module list_project_tasks(project=":app", group="Build") # Build with verbose output run_task(task=":app:build", args=["--info"]) # Run tests, skipping integration tests run_task(task=":app:test", args=["-x", "integrationTest"]) # Run multiple tasks run_task(task=[":core:build", ":app:assemble"]) # Check daemon health daemon_status() # Free up memory stop_daemon()

As Python Library

from gradle_mcp.gradle import GradleWrapper gradle = GradleWrapper("/path/to/gradle/project") # List projects projects = gradle.list_projects() for project in projects: print(f"Project: {project.name} at {project.path}") # List tasks with descriptions tasks = gradle.list_tasks(":app", include_descriptions=True) for group in tasks: print(f"\n{group.group}:") for task in group.tasks: print(f" {task.name}: {task.description}") # Run a task result = await gradle.run_task([":app:build"]) if result["success"]: print("✅ Build succeeded!") else: print(f"❌ Build failed: {result['error']}")

🏗️ Architecture

Safety by Design

Separated Cleaning — The run_task tool blocks all cleaning operations (clean, cleanBuild, etc.). Use the dedicated clean tool for artifact removal.
Gradle Wrapper — Always uses the project's Gradle wrapper for version consistency
Progress Reporting — Real-time progress via MCP protocol

Structured Error Output

The run_task and clean tools return structured error information optimized for LLM consumption:

class ErrorInfo: summary: str # e.g., "Build failed: 2 tasks failed with 12 compilation errors in 1 file" failed_tasks: list[FailedTask] # List of failed task names and reasons compilation_errors: list[CompilationError] # Deduplicated compilation errors class CompilationError: file: str # Full path (without file:// prefix) line: int column: int | None message: str class FailedTask: name: str # e.g., ":app:compileKotlin" reason: str # e.g., "Compilation finished with errors"

Example response:

{ "success": false, "error": { "summary": "Build failed: 2 tasks failed with 2 compilation errors in 1 file", "failed_tasks": [ {"name": ":app:compileKotlin", "reason": "Compilation finished with errors"} ], "compilation_errors": [ { "file": "/Users/dev/project/src/Main.kt", "line": 45, "column": 49, "message": "Argument type mismatch: actual type is 'String', but 'Int' was expected." } ] } }

Key features:

Deduplication — Identical errors from multiple targets (e.g., iOS Arm64 + Simulator) are merged
Clean paths — file:// prefix is stripped from file paths
Concise summaries — Human-readable summary with task/error/file counts
Token efficient — Structured data instead of raw build output

🧪 Development

Setup Development Environment

# Clone the repository git clone https://github.com/jermeyyy/gradle-mcp.git cd gradle-mcp # Install with dev dependencies uv sync --all-extras

Run Tests

pytest tests/

Code Quality

# Format code black src/ # Lint code ruff check src/ # Type checking mypy src/

Project Structure

gradle-mcp/ ├── src/gradle_mcp/ │ ├── __init__.py # Package initialization │ ├── server.py # MCP server implementation │ ├── gradle.py # Gradle wrapper interface │ └── dashboard/ # Web dashboard │ ├── app.py # Flask application │ ├── daemon_monitor.py # Daemon monitoring │ ├── log_store.py # Log management │ ├── templates/ # HTML templates │ └── static/ # CSS/JS assets ├── tests/ # Test suite ├── art/ # Screenshots and artwork ├── pyproject.toml # Project configuration └── README.md

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Ideas for Contribution

Additional build system support (Maven, Bazel)
Enhanced error visualization in dashboard
Build statistics and history
Custom task presets

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

Built with ❤️ for the Gradle and AI community

Report Bug • Request Feature