Gradle MCP 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.
Provides tools for interacting with Gradle projects, including listing projects and tasks, executing build tasks, running tests, and cleaning build artifacts through the Gradle Wrapper.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gradle MCP Server build the app module and run tests"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gradle MCP Server
A Model Context Protocol (MCP) server for seamless Gradle integration with AI assistants
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
Related MCP server: Build MCP Server
📸 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-mcpThe 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 |
| Root directory of the Gradle project | Current directory |
| Path to Gradle wrapper script | Auto-detected |
| JVM options for Gradle client | — |
| 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 path (e.g., |
|
| Include task descriptions (default: |
|
| Filter by task group (e.g., |
Returns: Grouped list of tasks
run_task(task, args)
Execute one or more Gradle tasks.
Parameter | Type | Description |
|
| Task(s) to run. Examples: |
|
| Additional Gradle arguments (e.g., |
Returns: TaskResult with:
success: bool— Whether the task completed successfullyerror: ErrorInfo | None— Structured error information (see Structured Error Output)
⚠️ Note: Cleaning tasks are blocked — use the
cleantool instead.
clean(project)
Clean build artifacts for a project.
Parameter | Type | Description |
|
| Project path (e.g., |
Returns: TaskResult with:
success: bool— Whether clean completed successfullyerror: 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.propertiesdaemon_enabled— Whether daemon is enabledparallel_enabled— Whether parallel execution is enabledcaching_enabled— Whether build caching is enabledmax_workers— Maximum worker countdistribution_url— Gradle distribution URLgradle_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_tasktool blocks all cleaning operations (clean,cleanBuild, etc.). Use the dedicatedcleantool 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 pathsConcise 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-extrasRun 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
Available Tools
7 toolscleanA
Clean build artifacts for a Gradle project.
Args: project: Project path (e.g., ':app'). Use None, empty string, or ':' for root project.
Returns: TaskResult with success status and error message if failed.
Inputs: project. Returns: Result of running a Gradle task.
daemon_statusA
Get status of Gradle daemon(s).
Returns current daemon status including running daemons and their info. Useful for monitoring daemon health and resource usage.
Returns: DaemonStatusResult with running status, list of daemon info, and optional error.
Inputs: no named parameters. Returns: Result of daemon status query.
get_gradle_configA
Get current Gradle configuration including memory settings.
Returns configuration from gradle.properties and gradle-wrapper.properties including JVM args, daemon settings, and Gradle version info. Useful for diagnosing memory issues or understanding project configuration.
Returns: GradleConfigResult with JVM args, daemon/parallel/caching settings, max workers, distribution URL, and Gradle version.
Inputs: no named parameters. Returns: Result of Gradle configuration query.
list_projectsB
List all Gradle projects in the workspace.
Returns: List of Gradle projects.
Inputs: no named parameters. Returns: result
list_project_tasksA
List all tasks available in a Gradle project.
Returns a nested structure grouped by task group. This is more compact than a flat list and avoids repeating project/group information for each task.
Args: project: Project path (e.g., ':app' or 'lib:module'). Use None, empty string, or ':' for root project. include_descriptions: If True, include task descriptions in the response. If False, return only task names for a more compact response. group: Optional group name to filter tasks (e.g., 'Build', 'Verification'). Case-insensitive. If not provided, all groups are returned.
Returns: List of grouped tasks. Each group contains a group name and list of tasks. If include_descriptions is True, tasks include name and description. If include_descriptions is False, tasks are just name strings.
Inputs: project, include_descriptions, group. Returns: result
run_taskA
Run one or more Gradle tasks.
Args: task: Task(s) to run. Single task, space-separated tasks, or list of tasks. Examples: 'build', ':app:build :core:build', [':core:build', ':app:assemble']. args: Optional Gradle arguments (e.g., ['--info', '-x', 'test']).
Returns: TaskResult with success status and error message if failed.
Inputs: task (required), args. Returns: Result of running a Gradle task.
stop_daemonA
Stop all Gradle daemons.
Stops all running Gradle daemons. Useful for freeing up memory or when experiencing daemon-related issues.
Returns: TaskResult with success status and error message if failed.
Inputs: no named parameters. Returns: Result of running a Gradle task.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct purpose with clear boundaries: clean removes artifacts, daemon_status monitors daemons, get_gradle_config retrieves configuration, list_projects enumerates projects, list_project_tasks shows available tasks, run_task executes tasks, and stop_daemon terminates daemons. There is no overlap or ambiguity between these functions.
Tools follow a consistent verb_noun pattern (e.g., clean, daemon_status, get_gradle_config, list_projects, list_project_tasks, run_task, stop_daemon), with all using snake_case. The minor deviation is 'get_gradle_config' using 'get_' prefix while others like 'list_' or 'run_' use different verbs, but overall naming is predictable and readable.
With 7 tools, the server is well-scoped for Gradle project management. It covers essential operations like cleaning, task execution, project listing, configuration retrieval, and daemon control, without being overly sparse or bloated. Each tool serves a clear purpose in the domain.
The toolset provides comprehensive coverage for core Gradle workflows, including project discovery, task management, execution, and daemon handling. A minor gap is the lack of tools for modifying configuration (e.g., updating gradle.properties) or advanced operations like dependency management, but agents can work around this with existing tools for most common tasks.
Maintenance
Related MCP Connectors
Build, test and cache insights for Xcode, Gradle and Bazel projects, for coding agents.
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Manage files and folders directly from your workspace. Read and write files, list directories, cre…
A graph-based task manager your agent can read and update: tasks, dependencies, blockers.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables management of Gradle-based Tomcat applications with capabilities for starting, stopping, restarting processes and querying application logs.61MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to manage development workflows by running build commands, executing tests, analyzing package.json files, installing dependencies, and performing code linting. Supports multiple package managers (npm, yarn, pnpm) and provides detailed error reporting for development operations.5MIT
- AlicenseAqualityDmaintenanceProvides structured build, compile, and test operations with parsed output to reduce token usage and improve readability.91MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to build, test, lint, and debug Android projects with concise Gradle output, filtered logcat, and connected-device inspection and interaction. It also supports setup across several agent clients and caps noisy output to save tokens.24 npmMIT