# MCP Ambari API

> 🚀 Natural-language Hadoop cluster management via MCP. Connect LLM agents (Claude, GPT, etc.) directly to Apache Ambari REST API — control services, inspect configs, query metrics, and manage alerts with AI. Built with FastMCP & aiohttp.

- **Type:** MCP server
- **Install:** `agentstack add mcp-call518-mcp-ambari-api`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [call518](https://agentstack.voostack.com/s/call518)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [call518](https://github.com/call518)
- **Source:** https://github.com/call518/MCP-Ambari-API
- **Website:** https://deepwiki.com/call518/MCP-Ambari-API

## Install

```sh
agentstack add mcp-call518-mcp-ambari-api
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Ambari API - Apache Hadoop Cluster Management Automation

> **🚀 Automate Apache Ambari operations with AI/LLM**: Conversational control for Hadoop cluster management, service monitoring, configuration inspection, and precise Ambari Metrics queries via Model Context Protocol (MCP) tools.

---

[](https://opensource.org/licenses/MIT)

[](https://www.buymeacoffee.com/call518)

[](https://github.com/call518/MCP-Ambari-API/actions/workflows/pypi-publish.yml)

---

## Architecture & Internal (DeepWiki)

[](https://deepwiki.com/call518/MCP-Ambari-API)

---

## 📋 Overview

**MCP Ambari API** is a powerful Model Context Protocol (MCP) server that enables seamless Apache Ambari cluster management through natural language commands. Built for DevOps engineers, data engineers, and system administrators who work with Hadoop ecosystems.

### Features

- ✅ **Interactive Ambari Operations Hub** – Provides an MCP-based foundation for querying and managing services through natural language instead of console or UI interfaces.
- ✅ **Real-time Cluster Visibility** – Comprehensive view of key metrics including service status, host details, alert history, and ongoing requests in a single interface.
- ✅ **Metrics Intelligence Pipeline** – Dynamically discovers and filters AMS appIds and metric names, connecting directly to time-series analysis workflows.
- ✅ **Automated Operations Workflow** – Consolidates repetitive start/stop operations, configuration checks, user queries, and request tracking into consistent scenarios.
- ✅ **Built-in Operational Reports** – Instantly delivers dfsadmin-style HDFS reports, service summaries, and capacity metrics through LLM or CLI interfaces.
- ✅ **Safety Guards and Guardrails** – Requires user confirmation before large-scale operations and provides clear guidance for risky commands through prompt templates.
- ✅ **LLM Integration Optimization** – Includes natural language examples, parameter mapping, and usage guides to ensure stable AI agent operations.
- ✅ **Flexible Deployment Models** – Supports stdio/streamable-http transport, Docker Compose, and token authentication for deployment across development and production environments.
- ✅ **Performance-Oriented Caching Architecture** – Built-in AMS metadata cache and request logging ensure fast responses even in large-scale clusters.
- ✅ **Scalable Code Architecture** – Asynchronous HTTP, structured logging, and modularized tool layers enable easy addition of new features.
- ✅ **Production-Validated** – Based on tools validated in test Ambari clusters, ready for immediate use in production environments.
- ✅ **Diversified Deployment Channels** – Available through PyPI packages, Docker images, and other preferred deployment methods.

### Docuement for Airflow REST-API

- [Ambari API Documents](https://github.com/apache/ambari/blob/trunk/ambari-server/docs/api/v1/index.md)

## Topics

`apache-ambari` `hadoop-cluster` `mcp-server` `cluster-automation` `devops-tools` `big-data` `infrastructure-management` `ai-automation` `llm-tools` `python-mcp`

---

## Example Queries - Cluster Info/Status

### [Go to More Example Queries](./src/mcp_ambari_api/prompt_template.md#9-example-queries)

---

---

---

## 🚀 QuickStart Guide /w Docker

> **Note:** The following instructions assume you are using the `streamable-http` mode for MCP Server.

### Flow Diagram of Quickstart/Tutorial

### 1. Prepare Ambari Cluster (Test Target)

To set up a Ambari Demo cluster, follow the guide at: [Install Ambari 3.0 with Docker](https://medium.com/@call518/install-ambari-3-0-with-docker-297a8bb108c8)

### 2. Run Docker-Compose

Start the `MCP-Server`, `MCPO`(MCP-Proxy for OpenAPI), and `OpenWebUI`.

1. Ensure Docker and Docker Compose are installed on your system.
1. Clone this repository and navigate to its root directory.
1. **Set up environment configuration:**
   ```bash
   # Copy environment template and configure your settings
   cp .env.example .env
   # Edit .env with your Ambari cluster information
   ```
1. **Configure your Ambari connection in `.env` file:**
   ```bash
   # Ambari cluster connection
   AMBARI_HOST=host.docker.internal
   AMBARI_PORT=7070
   AMBARI_USER=admin
   AMBARI_PASS=admin
   AMBARI_CLUSTER_NAME=TEST-AMBARI

   # Ambari Metrics (AMS) collector
   AMBARI_METRICS_HOST=host.docker.internal
   AMBARI_METRICS_PORT=16188
   AMBARI_METRICS_PROTOCOL=http
   AMBARI_METRICS_TIMEOUT=15
   
   # (Optional) Enable authentication for streamable-http mode
   # Recommended for production environments
   REMOTE_AUTH_ENABLE=false
   REMOTE_SECRET_KEY=your-secure-secret-key-here
   ```
1. Run:
   ```bash
   docker-compose up -d
   ```

- OpenWebUI will be available at: `http://localhost:${DOCKER_EXTERNAL_PORT_OPENWEBUI}` (default: 3001)
- The MCPO-Proxy will be accessible at: `http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY}` (default: 8001)  
- The MCPO API Docs: `http://localhost:${DOCKER_EXTERNAL_PORT_MCPO_PROXY}/mcp-ambari-api/docs`

### 3. Registering the Tool in OpenWebUI

> 📌 **Note**: Web-UI configuration instructions are based on OpenWebUI **v0.6.22**. Menu locations and settings may differ in newer versions.

1. logging in to OpenWebUI with an admin account
1. go to "Settings" → "Tools" from the top menu.
1. Enter the `mcp-ambari-api` Tool address (e.g., `http://localhost:8000/mcp-ambari-api`) to connect MCP Tools with your Ambari cluster.

### 4. More Examples: Using MCP Tools to Query Ambari Cluster

Below is an example screenshot showing how to query the Ambari cluster using MCP Tools in OpenWebUI:

#### Example Query - Cluster Configuration Review & Recommendations

#### Example Query - Restart HDFS Service

---

## 📈 Metrics & Trends

- **Terminology quick reference**
  - **appId**: Ambari Metrics Service groups every metric under an application identifier (e.g., `namenode`, `datanode`, `ambari_server`, `HOST`). Think of it as the component or service emitting that timeseries.
  - **metric name**: The fully qualified string Ambari uses for each timeseries (e.g., `jvm.JvmMetrics.MemHeapUsedM`, `dfs.datanode.BytesWritten`). Exact names are required when querying AMS.

- `list_common_metrics_catalog`: keyword search against the live metadata-backed metric catalog (cached locally). Use `search="heap"` or similar to narrow suggestions before running a time-series query.  
  _Example_: “Show the heap-related metrics available for the NameNode appId.”
- `list_ambari_metric_apps`: list discovered AMS `appId` values, optionally including metric counts; pass `refresh=true` or `limit` to control output.  
  _Example_: “List every appId currently exposed by AMS.”
- The natural-language query “AMS에서 사용 가능한 appId 목록만 보여줘” maps to `list_ambari_metric_apps` and returns the exact identifiers you can copy into other tools.
- `list_ambari_metrics_metadata`: raw AMS metadata explorer (supports `app_id`, `metric_name_filter`, `host_filter`, `search`, adjustable `limit`, default 50).  
  _Example_: “Give me CPU-related metric metadata under HOST.”
- `query_ambari_metrics`: fetch time-series data; the tool auto-selects curated metric names, falls back to metadata search when needed, and honors Ambari's default precision unless you explicitly supply `precision="SECONDS"`, etc.  
  _Examples_: “Plot the last 30 minutes of `jvm.JvmMetrics.MemHeapUsedM` for the NameNode.” / “Compare `jvm.JvmMetrics.MemHeapUsedM` for DataNode hosts `bigtop-hostname0.demo.local` and `bigtop-hostname1.demo.local` over the past 30 minutes.”
- `hdfs_dfadmin_report`: produce a DFSAdmin-style capacity/DataNode summary (mirrors `hdfs dfsadmin -report`).

**Live Metric Catalog (via AMS metadata)**
- Metric names are discovered on demand from `/ws/v1/timeline/metrics/metadata` and cached for quick reuse.
- Use `list_common_metrics_catalog` or the `ambari-metrics://catalog/all` resource (append `?refresh=true` to bypass the cache) to inspect the latest `appId → metric` mapping. Query `ambari-metrics://catalog/apps` to list appIds or `ambari-metrics://catalog/` for a single app.
- Typical appIds include `ambari_server`, `namenode`, `datanode`, `nodemanager`, `resourcemanager`, and `HOST`, but the list adapts to whatever the Ambari Metrics service advertises in your cluster.

---

## 🔍 Ambari Metrics Query Requirements (Exact-Match Workflow)

Recent updates removed natural-language metric guessing in favor of deterministic, catalog-driven lookups. Keep the following rules in mind when you (or an LLM agent) call `query_ambari_metrics`:

1. **Always pass an explicit `app_id`.** If it is missing or unsupported, the tool returns a list of valid appIds and aborts so you can choose one manually.
2. **Specify exact metric names.** Use `list_common_metrics_catalog(app_id="", search="keyword")`, `list_ambari_metric_apps` (to discover appIds), or the `ambari-metrics://catalog/` resource to browse the live per-app metric set and copy the identifier (e.g., `jvm.JvmMetrics.MemHeapUsedM`).
3. **Host-scope behavior**: When `hostnames` is omitted the API returns cluster-wide aggregates. Provide one or more hosts (comma-separated) to focus on specific nodes.
4. **No fuzzy matches.** The server now calls Ambari exactly as requested. If the metric is wrong or empty, Ambari will simply return no datapoints—double-check the identifier via `/ws/v1/timeline/metrics/metadata`.

Example invocation:

```plaintext
query_ambari_metrics(
  metric_names="jvm.JvmMetrics.MemHeapUsedM",
  app_id="nodemanager",
  duration="1h",
  group_by_host=true
)
```

For multi-metric lookups, pass a comma-separated list of exact names. Responses document any auto-applied host filters so you can copy/paste them into subsequent requests.

---

## 🐛 Usage & Configuration

This MCP server supports two connection modes: **stdio** (traditional) and **streamable-http** (Docker-based). You can configure the transport mode using CLI arguments or environment variables.

**Configuration Priority:** CLI arguments > Environment variables > Default values

### CLI Arguments

- `--type` (`-t`): Transport type (`stdio` or `streamable-http`) - Default: `stdio`
- `--host`: Host address for HTTP transport - Default: `127.0.0.1`  
- `--port` (`-p`): Port number for HTTP transport - Default: `8000`
- `--auth-enable`: Enable Bearer token authentication for streamable-http mode - Default: `false`
- `--secret-key`: Secret key for Bearer token authentication (required when auth enabled)

### Environment Variables

| Variable | Description | Default | Project Default |
|----------|-------------|---------|-----------------|
| `PYTHONPATH` | Python module search path for MCP server imports | - | `/app/src` |
| `MCP_LOG_LEVEL` | Server logging verbosity (DEBUG, INFO, WARNING, ERROR) | `INFO` | `INFO` |
| `FASTMCP_TYPE` | MCP transport protocol (stdio for CLI, streamable-http for web) | `stdio` | `streamable-http` |
| `FASTMCP_HOST` | HTTP server bind address (0.0.0.0 for all interfaces) | `127.0.0.1` | `0.0.0.0` |
| `FASTMCP_PORT` | HTTP server port for MCP communication | `8000` | `8000` |
| `REMOTE_AUTH_ENABLE` | Enable Bearer token authentication for streamable-http mode**Default: false** (if undefined, empty, or null) | `false` | `false` |
| `REMOTE_SECRET_KEY` | Secret key for Bearer token authentication**Required when REMOTE_AUTH_ENABLE=true** | - | `your-secret-key-here` |
| `AMBARI_HOST` | Ambari server hostname or IP address | `127.0.0.1` | `host.docker.internal` |
| `AMBARI_PORT` | Ambari server port number | `8080` | `8080` |
| `AMBARI_USER` | Username for Ambari server authentication | `admin` | `admin` |
| `AMBARI_PASS` | Password for Ambari server authentication | `admin` | `admin` |
| `AMBARI_CLUSTER_NAME` | Name of the target Ambari cluster | `TEST-AMBARI` | `TEST-AMBARI` |
| `DOCKER_EXTERNAL_PORT_OPENWEBUI` | Host port mapping for Open WebUI container | `8080` | `3001` |
| `DOCKER_EXTERNAL_PORT_MCP_SERVER` | Host port mapping for MCP server container | `8080` | `18001` |
| `DOCKER_EXTERNAL_PORT_MCPO_PROXY` | Host port mapping for MCPO proxy container | `8000` | `8001` |

**Note**: `AMBARI_CLUSTER_NAME` serves as the default target cluster for operations when no specific cluster is specified. All environment variables can be configured via the `.env` file. 

**Transport Selection Logic:**

**Configuration Priority:** CLI arguments > Environment variables > Default values

**Transport Selection Logic:**

- **CLI Priority**: `--type streamable-http --host 0.0.0.0 --port 18001`
- **Environment Priority**: `FASTMCP_TYPE=streamable-http FASTMCP_HOST=0.0.0.0 FASTMCP_PORT=18001`
- **Legacy Support**: `FASTMCP_PORT=18001` (automatically enables streamable-http mode)
- **Default**: `stdio` mode when no configuration is provided

### Environment Setup

```bash
# 1. Clone the repository
git clone https://github.com/call518/MCP-Ambari-API.git
cd MCP-Ambari-API

# 2. Set up environment configuration
cp .env.example .env

# 3. Configure your Ambari connection in .env file
AMBARI_HOST=your-ambari-host
AMBARI_PORT=your-ambari-port  
AMBARI_USER=your-username
AMBARI_PASS=your-password
AMBARI_CLUSTER_NAME=your-cluster-name
```

---

## 🔐 Security & Authentication

### Bearer Token Authentication

For `streamable-http` mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.

#### Configuration

**Enable Authentication:**

```bash
# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here
```

**Or via CLI:**

```bash
python -m mcp_ambari_api --type streamable-http --auth-enable --secret-key your-secure-secret-key-here
```

#### Security Levels

1. **stdio mode** (Default): Local-only access, no authentication needed
2. **streamable-http + REMOTE_AUTH_ENABLE=false/undefined**: Remote access without authentication ⚠️ **NOT RECOMMENDED for production**
3. **streamable-http + REMOTE_AUTH_ENABLE=true**: Remote access with Bearer token authentication ✅ **RECOMMENDED for production**

> **🔒 Default Policy**: `REMOTE_AUTH_ENABLE` defaults to `false` if undefined, empty, or null. This ensures the server starts even without explicit authentication configuration.

#### Client Configuration

When authentication is enabled, MCP clients must include the Bearer token in the Authorization header:

```json
{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}
```

#### Security Best Practices

- **Always enable authentication** when using streamable-http mode in production
- **Use strong, randomly generated secret keys** (32+ characters recommended)
- **Use HTTPS** when possible (configure reverse proxy with SSL/TLS)
- **Restrict network access** using firewalls or network policies
- **Rotate secret keys regularly** for enhanced security
- **Monitor access logs** for unauthorized access attempts

#### Error Handling

When authentication fails, the server returns:
- **401 Unauthorized** for missing or invalid tokens
- **Detailed error messages** in JSON format for debugging

---

### Method 1: Local MCP (transport="stdio")

```json
{
  "mcpServers": {
    "mcp-ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "host.docker.internal",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "TEST-AMBARI",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

### Method 2: Remote MCP (transport="streamable-http")

**On MCP-Client Host:**

```json
{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http",
      "url": "http://localhost:18001/mcp"
    }
  }
}
```

**With Bearer Token Authentication (Recommended for production):**

```json
{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamabl

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [call518](https://github.com/call518)
- **Source:** [call518/MCP-Ambari-API](https://github.com/call518/MCP-Ambari-API)
- **License:** MIT
- **Homepage:** https://deepwiki.com/call518/MCP-Ambari-API

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-call518-mcp-ambari-api
- Seller: https://agentstack.voostack.com/s/call518
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.