<div align="center">
<p align="center">
<img src="art/gradle_logo.png" alt="Gradle" width="150"/>
</p>
# Gradle MCP Server
**A Model Context Protocol (MCP) server for seamless Gradle integration with AI assistants**
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/jlowin/fastmcp)
*Empower your AI coding assistant to build, test, and manage Gradle projects with real-time monitoring*
[Features](#-features) • [Installation](#-installation) • [Quick Start](#-quick-start) • [Web Dashboard](#-web-dashboard) • [API Reference](#-mcp-tools-api) • [Contributing](#-contributing)
</div>
---
## ✨ 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
<p align="center">
<img src="art/dashboard.png" alt="Gradle MCP Dashboard" width="100%">
</p>
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
<p align="center">
<img src="art/logs.png" alt="Build Logs Viewer" width="100%">
</p>
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
```bash
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
```bash
# Navigate to your Gradle project directory
cd /path/to/your/gradle/project
# Start the MCP server
uv run gradle-mcp
```
The server will:
1. Auto-detect the Gradle wrapper in the current directory
2. Start the web dashboard at `http://localhost:3333` (or higher if port already occupied)
3. 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`:
```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
```bash
# 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](#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](#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
```python
# 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
```python
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:
```python
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:**
```json
{
"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
```bash
# 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
```bash
pytest tests/
```
### Code Quality
```bash
# 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:
1. **Fork** the repository
2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
4. **Push** to the branch (`git push origin feature/amazing-feature`)
5. **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](LICENSE) file for details.
---
<div align="center">
**Built with ❤️ for the Gradle and AI community**
[Report Bug](https://github.com/jermeyyy/gradle-mcp/issues) • [Request Feature](https://github.com/jermeyyy/gradle-mcp/issues)
</div>
