# How to Get HDFS Capacity Reports Using `hdfs_dfadmin_report` in MCP Ambari API

> Learn how to get HDFS capacity reports using hdfs_dfadmin_report in MCP Ambari API. This tool queries Ambari Metrics and REST API for capacity metrics.

- Repository: [JungJungIn/mcp-ambari-api](https://github.com/call518/mcp-ambari-api)
- Tags: how-to-guide
- Published: 2026-02-26

---

**The `hdfs_dfadmin_report` tool in the `call518/mcp-ambari-api` repository retrieves HDFS capacity metrics by querying the Ambari Metrics Service (AMS) and falling back to the Ambari REST API when necessary, formatting the output to match the native `hdfs dfsadmin -report` command.**

The `call518/mcp-ambari-api` project provides a Model Context Protocol (MCP) server that exposes Hadoop cluster operations as callable tools. Among these, **`hdfs_dfadmin_report`** offers a programmatic way to monitor HDFS storage utilization without requiring direct shell access to NameNode hosts.

## What Is `hdfs_dfadmin_report`?

`hdfs_dfadmin_report` is an MCP tool defined in [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) that simulates the output of the Hadoop command `hdfs dfsadmin -report`. Instead of executing shell commands on the cluster, the tool leverages the **Ambari Metrics Service (AMS)** to fetch live HDFS metrics and formats them into a human-readable report.

The tool accepts a single optional parameter:

- **`lookback_minutes`** (int): The time window in minutes to look back for metric values (default varies based on implementation).

## How `hdfs_dfadmin_report` Works

The implementation follows a five-stage pipeline to ensure reliable data retrieval even when AMS is partially unavailable.

### Step 1: AMS Availability Check

Before attempting metric collection, the tool calls **`check_ams_availability()`** from [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/functions.py). If the Ambari Metrics Service is unreachable, the tool immediately returns a descriptive error message rather than failing silently.

```python

# From mcp_main.py lines 50-52

if not check_ams_availability():
    return "Error: Ambari Metrics Service (AMS) is not available. Cannot retrieve HDFS metrics."

```

### Step 2: Metric Collection from Ambari Metrics Service

When AMS is available, the tool constructs a mapping of critical HDFS metrics and fetches them concurrently using **`fetch_latest_metric_value`**. The specific metrics queried include:

- `dfs.FSNamesystem.CapacityTotal`
- `dfs.FSNamesystem.CapacityUsed`
- `dfs.FSNamesystem.CapacityRemaining`
- `dfs.FSNamesystem.CapacityNonDFSUsed`
- `dfs.FSNamesystem.BlocksTotal`
- `dfs.FSNamesystem.UnderReplicatedBlocks`
- `dfs.FSNamesystem.CorruptBlocks`
- `dfs.FSNamesystem.MissingBlocks`

This logic resides in [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) between lines 87-99.

### Step 3: Fallback to Ambari REST API

If AMS returns null or unconfigured values for capacity metrics, the tool executes a fallback mechanism. It queries the Ambari REST endpoint `/clusters/<cluster>/services/HDFS/components/NAMENODE` using **`make_ambari_request`** and extracts equivalent metrics from the JSON response.

This fallback ensures that capacity reports remain available even during AMS outages or metric collection gaps, as implemented in lines 112-139 of [`mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/mcp_main.py).

### Step 4: Data Conversion and Formatting

Raw metric values (often in bytes) are converted to human-readable formats using helper functions:

- **`to_float`**: Safely converts string values to floats
- **`format_bytes`**: Transforms byte counts into TB, GB, or MB strings
- **`safe_percent`**: Calculates percentages without division-by-zero errors

These utilities appear in [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) lines 78-85.

### Step 5: Report Assembly

Finally, the tool calculates derived values such as **Present Capacity** and **DFS Used%**, then assembles a multi-line text block that mirrors the classic `hdfs dfsadmin -report` output format. This formatted string is returned to the MCP client.

The report generation logic is located in lines 300-322 of [`mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/mcp_main.py).

## How to Call `hdfs_dfadmin_report`

The tool is exposed through the MCP server and can be invoked via multiple transport methods.

### Using the MCP CLI (stdio mode)

Start the server in stdio mode and call the tool interactively:

```bash

# Start the server

PYTHONPATH=./src uv run python -m mcp_ambari_api

# In the interactive prompt, request the report

> hdfs_dfadmin_report(lookback_minutes=15)

```

**Sample output:**

```

Configured Capacity: 12.34 TB
Present Capacity:    11.80 TB
DFS Used%:           78.45%
DFS Remaining%:      21.55%
Non DFS Used:        4.20 GB (0.04%)
Under Replicated:    12
Corrupt Replicas:    0
Missing Blocks:      0

```

### Using HTTP/Streamable HTTP Transport

Send a POST request to the MCP endpoint:

```bash
curl -X POST http://localhost:8000/mcp-ambari-api/mcp \
  -H "Content-Type: application/json" \
  -d '{
        "tool": "hdfs_dfadmin_report",
        "args": { "lookback_minutes": 20 }
      }'

```

The response body contains the formatted report text.

### Programmatic Python Invocation

Call the tool from another Python process using urllib:

```python
import json
import urllib.request

payload = {
    "tool": "hdfs_dfadmin_report",
    "args": {"lookback_minutes": 10}
}
data = json.dumps(payload).encode()

req = urllib.request.Request(
    "http://localhost:8000/mcp-ambari-api/mcp",
    data=data,
    headers={"Content-Type": "application/json"},
    method="POST",
)

with urllib.request.urlopen(req) as resp:
    print(resp.read().decode())

```

## Key Source Files and Implementation Details

Understanding the codebase structure helps when extending or debugging the tool:

| File | Role | Key Functions |
|------|------|---------------|
| [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) | Tool declaration and report logic | `hdfs_dfadmin_report()`, `to_float()`, `format_bytes()`, `safe_percent()` |
| [`src/mcp_ambari_api/functions.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/functions.py) | AMS and Ambari REST utilities | `check_ams_availability()`, `fetch_latest_metric_value()`, `make_ambari_request()` |
| [`src/mcp_ambari_api/__main__.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/__main__.py) | Server entry point | Starts stdio or HTTP transport |
| [`src/mcp_ambari_api/prompt_template.md`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/prompt_template.md) | Natural language query examples | Documents example prompts that map to the tool |

The tool specifically queries these HDFS metrics from AMS:
- `dfs.FSNamesystem.CapacityTotal`
- `dfs.FSNamesystem.CapacityUsed`
- `dfs.FSNamesystem.CapacityRemaining`
- `dfs.FSNamesystem.CapacityNonDFSUsed`

When AMS is unavailable, it falls back to the Ambari REST API endpoint `/clusters/{cluster}/services/HDFS/components/NAMENODE`.

## Summary

- **`hdfs_dfadmin_report`** is an MCP tool in `call518/mcp-ambari-api` that retrieves HDFS capacity data without requiring shell access to Hadoop nodes.
- The tool prioritizes the **Ambari Metrics Service (AMS)** for real-time metrics but automatically **falls back to the Ambari REST API** if AMS is down or missing data.
- It calculates **Present Capacity**, **DFS Used%**, and **Non-DFS Used** from raw byte values, formatting them to match the classic `hdfs dfsadmin -report` output.
- You can invoke the tool via **MCP stdio CLI**, **HTTP POST requests**, or **programmatically** from Python applications.

## Frequently Asked Questions

### What metrics does `hdfs_dfadmin_report` return?

The tool returns a comprehensive capacity report including **Configured Capacity**, **Present Capacity**, **DFS Used** (percentage and bytes), **DFS Remaining**, **Non DFS Used**, and block health statistics such as **Under Replicated Blocks**, **Corrupt Replicas**, and **Missing Blocks**. These values mirror the output of the native Hadoop command `hdfs dfsadmin -report`.

### Does `hdfs_dfadmin_report` require the Ambari Metrics Service to be running?

While the tool prefers to fetch data from the **Ambari Metrics Service (AMS)** for the most current values, it does not strictly require AMS to be available. If `check_ams_availability()` detects that AMS is down or if specific metrics return null, the tool automatically falls back to querying the **Ambari REST API** directly via `make_ambari_request()`.

### How does the tool format raw byte values into readable strings?

The tool uses helper functions defined in [`src/mcp_ambari_api/mcp_main.py`](https://github.com/call518/mcp-ambari-api/blob/main/src/mcp_ambari_api/mcp_main.py) to transform raw metric values. **`to_float()`** safely converts strings to floats, **`format_bytes()`** converts byte counts into human-readable units (TB, GB, MB), and **`safe_percent()`** calculates percentages while handling division-by-zero scenarios. These utilities ensure the final report is both accurate and readable.

### Can I customize the time range for the metrics query?

Yes, the tool accepts a **`lookback_minutes`** parameter that specifies how far back to query for metric values. This parameter is passed to `fetch_latest_metric_value` when querying AMS, allowing you to retrieve capacity data from a specific time window rather than just the latest instantaneous value. If using the HTTP transport, include this parameter in the JSON payload's `args` object.