Skip to main content

MCP Ambari API

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

License: MIT PyPI Docker Pulls

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

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.

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.
  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 and uv; 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
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.

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.

Connect OpenWebUI directly to MCP

In OpenWebUI 0.7.2, add an MCP connection using the URL visible from the OpenWebUI container:

http://mcp-server:8000/mcp

Use http://localhost:18001/mcp only from a client running on the Docker host. MCPO is not required for direct MCP connections; it remains in the standard stack for OpenAPI-compatible clients.

To start without MCPO:

docker compose up -d mcp-server open-webui

Other installation methods

PyPI with uvx

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

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

The canonical tool-selection and safety guidance is in prompt_template.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:

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 or newer
  • MCP stdio and Streamable HTTP transports
  • Claude Desktop MCPB through the UV runtime
  • Docker Compose stack with OpenWebUI 0.7.2
  • 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 Compose example seeds OpenWebUI with:

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

uv sync --dev
uv run ruff check src tests scripts
uv run python -m unittest discover -s tests -v

Run MCP Inspector against local source:

./run-mcp-inspector-local.sh

Build a local MCPB using a canonical semantic version:

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

Metadata

Release files for mcp-ambari-api 3.8.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-ambari-api 3.8.3
File Size Uploaded Provenance Actions
mcp_ambari_api-3.8.3.tar.gz 956.0 kB With provenance Details for mcp_ambari_api-3.8.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mcp-ambari-api 3.8.3
File Interpreter ABI Platform Actions
mcp_ambari_api-3.8.3-py3-none-any.whl Python 3 none any Details for mcp_ambari_api-3.8.3-py3-none-any.whl

Total release size: 1.0 MB

Release files / mcp_ambari_api-3.8.3.tar.gz

Download URL mcp_ambari_api-3.8.3.tar.gz
Size 956.0 kB
Tags Source
SHA-256 checksum
How to use checksums
612c62dfacc3ad571b55ac30b1e073ff48b50c4dcfa97fc7ad6c2244912131e2
BLAKE2b-256 checksum
How to use checksums
0a8cf31ad8318854017a5f11a2a4eb00f49ce4f66c4c5d2196cd5768b8c25e53
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / mcp_ambari_api-3.8.3-py3-none-any.whl

Download URL mcp_ambari_api-3.8.3-py3-none-any.whl
Size 66.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0e812fa30c1e495da1edfb25b0604798748ecf5ce5757f159e90b4de4d5c2b8d
BLAKE2b-256 checksum
How to use checksums
7b91af547fa512cb3bc072584ecb77df3cf4187e59ea4a22adcf612ed2916e0e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for mcp-ambari-api 3.8.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mcp_ambari_api-3.8.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.8.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page