Skip to main content
Glama
Gradle MCP Server
by jermeyyy

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


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

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:

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


Built with ❤️ for the Gradle and AI community

Report Bug • Request Feature

Available Tools

7 tools
cleanA

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

    A3.9/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables management of Gradle-based Tomcat applications with capabilities for starting, stopping, restarting processes and querying application logs.
      6
      1
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      5
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT