Skip to main content
Glama
README.md
# MCP Ambari API

> Manage and inspect Apache Ambari clusters from Claude Desktop, OpenWebUI, or any MCP client.

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![PyPI](https://img.shields.io/pypi/v/MCP-Ambari-API)](https://pypi.org/project/MCP-Ambari-API/)
[![Docker Pulls](https://img.shields.io/docker/pulls/call518/mcp-server-ambari-api)](https://hub.docker.com/r/call518/mcp-server-ambari-api)

MCP Ambari API turns common Hadoop operations into MCP tools. It can inspect
cluster health, services, hosts, alerts, configurations, requests, and Ambari
Metrics data, and can perform service operations with safety guidance for
high-impact actions.

Example requests:

- “Show the current status of every service.”
- “List critical Ambari alerts and their affected hosts.”
- “Generate an HDFS capacity report.”
- “Find NameNode heap metrics available in AMS.”
- “Restart HDFS after showing me the affected components.”

**More requests to try:** see
[Example queries by area](docs/usage-guide.md#example-queries-by-area) for
cluster and services, service operations, requests and tasks, hosts,
configurations, users, alerts, and metrics.

## Quick start

Choose one installation method. MCPB is the shortest path for Claude Desktop;
Docker Compose provides the full OpenWebUI, MCP server, and optional MCPO stack.

<a id="claude-desktop-integration"></a>

### Claude Desktop with MCPB

Prerequisites:

- Claude Desktop for macOS or Windows with MCPB extension support
- Network access from the desktop to the Ambari server and, when used, the
  Ambari Metrics collector

1. Download `mcp-ambari-api-<version>.mcpb` from the
   [latest GitHub Release](https://github.com/call518/MCP-Ambari-API/releases/latest).
2. In Claude Desktop, open **Settings → Extensions → Advanced settings →
   Install Extension…**.
3. Select the downloaded bundle.
4. Enter the Ambari host, port, username, password, cluster name, and Metrics
   collector settings. The password is declared as a sensitive field.
5. Ask a read-only verification question such as “Show the Ambari cluster
   status.”

The bundle uses stdio transport, `uv`, and Python `3.12`; it does not expose a
listening port.
MCPB settings are stored by the desktop host and are not written into this
repository.

### OpenWebUI with Docker Compose

Prerequisites:

- Docker Engine with Docker Compose
- A reachable Ambari cluster
- An OpenWebUI model provider and a model that supports tool calling

```bash
git clone https://github.com/call518/MCP-Ambari-API.git
cd MCP-Ambari-API
cp .env.example .env
cp mcp-config.json.http mcp-config.json.http.local
chmod 600 .env mcp-config.json.http.local
```

Edit `.env` with the Ambari connection values. If remote MCP authentication is
enabled, replace `<REMOTE_SECRET_KEY>` in both `.env` and
`mcp-config.json.http.local` with the same strong secret.

```bash
docker compose up -d
docker compose ps
```

Default host endpoints:

| Service | URL | Purpose |
|---|---|---|
| OpenWebUI | `http://localhost:3001` | Chat interface |
| MCP server | `http://localhost:18001/mcp` | Direct Streamable HTTP MCP |
| MCPO | `http://localhost:8001/mcp-ambari-api/docs` | Optional OpenAPI compatibility layer |

The published ports bind to `127.0.0.1` by default. Set
`DOCKER_BIND_ADDRESS` only when remote access is required, and enable
authentication plus TLS at the network boundary before exposing the services.

#### Configure OpenWebUI

Open `http://localhost:3001`, create the administrator account, and configure a
model provider under **Settings → Admin → Connections**. For OpenAI, add a
connection with these values:

| Field | Value |
|---|---|
| URL | `https://api.openai.com/v1` |
| Auth | `Bearer` |
| API key | Your OpenAI API key |
| API Type | `Chat Completions` |

`Chat Completions` must be used with the Quick Start's default
`DEFAULT_MODEL_PARAMS={"reasoning_effort":"none"}` setting. To use an OpenAI
reasoning model with reasoning enabled instead, set `DEFAULT_MODEL_PARAMS={}`
before the first start, select `Responses`, and leave **Reasoning Effort** at
**Default** in the global, per-model, and chat settings. Mixing `Responses`
with `reasoning_effort=none`, or `Chat Completions` with another reasoning
effort, can cause tool calls to fail.

Confirm that the model appears in a new chat, then add one of the following
external tool-server connections under **Settings → Admin → Tools →
Integrations**.

**Option A: Direct MCP (recommended)**

Add a connection of type `MCP (Streamable HTTP)` using the URL visible from the
OpenWebUI container:

```text
http://mcp-server:8000/mcp
```

Use `http://localhost:18001/mcp` only from a client running on the Docker host.
Use authentication `None` unless `REMOTE_AUTH_ENABLE=true`; when authentication
is enabled, use `Bearer` with the configured `REMOTE_SECRET_KEY`.

**Option B: MCPO (OpenAPI)**

Add a connection of type `OpenAPI` with this URL:

```text
http://mcpo-proxy:8000/mcp-ambari-api
```

MCPO is not required for OpenWebUI; it remains in the standard stack for
OpenAPI-compatible clients. Use the Compose service URLs above rather than
`localhost` because OpenWebUI resolves them from inside its container.

To start without MCPO:

```bash
docker compose up -d mcp-server open-webui
```

### Other installation methods

#### PyPI with uvx

```json
{
  "mcpServers": {
    "mcp-ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "ambari.example.com",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "<AMBARI_USER>",
        "AMBARI_PASS": "<AMBARI_PASSWORD>",
        "AMBARI_CLUSTER_NAME": "<AMBARI_CLUSTER_NAME>",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

#### Remote Streamable HTTP

```json
{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer <REMOTE_SECRET_KEY>"
      }
    }
  }
}
```

## Capabilities

- Cluster, service, component, host, request, user, and alert inspection
- Service start, stop, restart, maintenance, and configuration workflows
- HDFS `dfsadmin`-style capacity and DataNode reports
- Live Ambari Metrics metadata discovery and exact-name time-series queries
- stdio and Streamable HTTP transports
- Optional bearer authentication for Streamable HTTP

Cross-tool safety and reporting rules are sent to clients as MCP server
instructions from
[`server_instructions.md`](src/mcp_ambari_api/server_instructions.md). Tool availability
can evolve, so MCP clients should use `tools/list` rather than relying on a
copied static tool list.

## Configuration

CLI arguments take precedence over environment variables, which take
precedence over defaults.

### Server settings

| Variable | Default | Description |
|---|---:|---|
| `FASTMCP_TYPE` | `stdio` | `stdio` or `streamable-http` |
| `FASTMCP_HOST` | `127.0.0.1` | HTTP bind address |
| `FASTMCP_PORT` | `8000` | HTTP listen port |
| `MCP_LOG_LEVEL` | `INFO` | Log level |
| `REMOTE_AUTH_ENABLE` | `false` | Enable HTTP bearer authentication |
| `REMOTE_SECRET_KEY` | empty | Required when authentication is enabled |

CLI equivalents are `--type`, `--host`, `--port`, `--auth-enable`, and
`--secret-key`.

### Ambari settings

| Variable | Default | Description |
|---|---:|---|
| `AMBARI_HOST` | `localhost` | Ambari server host |
| `AMBARI_PORT` | `8080` | Ambari server port |
| `AMBARI_USER` | `admin` | Ambari username |
| `AMBARI_PASS` | `admin` | Ambari password |
| `AMBARI_CLUSTER_NAME` | `c1` | Default target cluster |
| `AMBARI_METRICS_HOST` | Ambari host | Metrics collector host |
| `AMBARI_METRICS_PORT` | `6188` | Metrics collector port |
| `AMBARI_METRICS_PROTOCOL` | `http` | Metrics collector protocol |
| `AMBARI_METRICS_TIMEOUT` | `10` | Metrics request timeout in seconds |

## Metrics workflow

Ambari metric names are exact identifiers rather than natural-language labels.
Use this sequence:

1. Call `list_ambari_metric_apps` to discover valid app IDs.
2. Call `list_common_metrics_catalog` or
   `list_ambari_metrics_metadata` to find an exact metric name.
3. Call `query_ambari_metrics` with an explicit `app_id` and exact metric name.

Example:

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

## Safety and security

- Keep `.env` and `mcp-config.json.http.local` outside Git. The tracked files
  contain placeholders only.
- Use a unique, strong `REMOTE_SECRET_KEY`; never reuse an Ambari password as
  the MCP bearer token.
- Plain HTTP does not protect credentials in transit. Use a TLS reverse proxy
  for remote access.
- Keep unauthenticated development services bound to localhost.
- Review service-wide start, stop, restart, and configuration changes before
  approving them in the MCP client.

## Compatibility

- Python `3.12.x`
- MCP stdio and Streamable HTTP transports
- Claude Desktop MCPB through the UV runtime
- Docker Compose stack with OpenWebUI `0.13.3`
- Apache Ambari environments that expose the Ambari REST API; exact behavior
  can vary by Ambari and Hadoop component version

## Troubleshooting

### OpenAI reasoning model rejects tool calls

The connection's **API Type** and **Reasoning Effort** must match:

| Setup | API Type | Reasoning Effort |
|---|---|---|
| Quick Start default | `Chat Completions` | `none` |
| Reasoning with tools | `Responses` | `Default` in every scope |

The Compose example seeds the Quick Start default into OpenWebUI with:

```dotenv
DEFAULT_MODEL_PARAMS={"reasoning_effort":"none"}
```

OpenWebUI stores this value in its database on first startup. For an existing
`open-webui-data` volume, set **Reasoning Effort** to `none` in the Admin UI or
per-model settings instead. Per-chat settings can override both. Do not delete
the data volume as a troubleshooting shortcut. If using `Responses`, remove
the parameter from the global, per-model, and chat settings and leave Reasoning
Effort at `Default`. Remove the global parameter if the selected provider does
not support it.

### MCPO returns 401 Unauthorized

Check, without printing the secret itself:

1. `REMOTE_AUTH_ENABLE` in `.env`.
2. Whether `REMOTE_SECRET_KEY` is set.
3. Whether `mcp-config.json.http.local` still contains the placeholder.
4. Whether its bearer token matches the server secret.
5. Whether the MCPO container was recreated after the change.

An error emitted while cleaning up the connection can follow the initial 401;
diagnose the first HTTP error first.

### Direct MCP works but MCPO fails

These are separate client paths. Verify the direct endpoint
`http://mcp-server:8000/mcp` and the MCPO-mounted local config independently.

### Ambari connection fails

Verify host reachability from the process or container, Ambari credentials,
cluster name spelling, and the server port. `localhost` inside a container is
the container itself; use `host.docker.internal` for a service on the Docker
host.

## Development

Install and run with the existing uv project:

```bash
uv sync --dev
uv run ruff check src tests scripts
uv run pytest
```

Run MCP Inspector against local source:

```bash
./run-mcp-inspector-local.sh
```

Build a local MCPB using a canonical semantic version:

```bash
scripts/build-mcpb.sh 0.0.0 /tmp/mcp-ambari-api-mcpb
unzip -l /tmp/mcp-ambari-api-mcpb/mcp-ambari-api-0.0.0.mcpb
```

Tagged releases build the wheel, source distribution, and MCPB. Publication to
TestPyPI and PyPI completes before the GitHub Release is created with the MCPB
attached.

## Contributing

Keep changes focused, add tests for behavior changes, and verify documentation
commands against the current configuration. Open an issue before making a
breaking public API or configuration change.

## License

[MIT](LICENSE)

TDQS

B3.2/5.0

Scored across 29 tools

Disambiguation3/5

Several tools have overlapping purposes: get_service_details already includes state and components, blurring the line with get_service_status and get_service_components; get_host_details can retrieve all hosts with details, overlapping list_hosts; and the deprecated get_current_alerts remains alongside get_alerts_history. Descriptions help, but an agent could misselect, especially for service/host introspection and alert retrieval.

Naming Consistency4/5

Nearly all tools follow snake_case with a verb_noun pattern (get_, list_, start_, stop_, restart_, dump_). Exceptions like hdfs_dfadmin_report (noun phrase) and mixed get_/list_ for retrieval are minor deviations that don't hinder readability.

Tool Count2/5

29 tools is above the 25-tool threshold for 'too many' given the guideline; some consolidation is possible (e.g., deprecating get_current_alerts, merging service status/components into details). While Ambari is complex, the surface feels heavy with redundant read operations.

Completeness3/5

Core lifecycle operations for services and components (start/stop/restart) and read access for hosts, requests, alerts, metrics, and users are present. However, notable gaps exist: no configuration update (dump_configurations only reads), no user CRUD beyond list/get, and no host add/remove or service installation—operations likely needed for full cluster management.

Maintenance

ActivityActive
ResponsivenessNo recent community issues