jermeyyy/gradle-mcp

✨ 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:

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:

{
  "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

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.

Returns: Grouped list of tasks

run_task(task, args)

Execute one or more Gradle tasks.

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.

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:

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 file for details.