MCP Ambari API
Manage and inspect Apache Ambari clusters from Claude Desktop, OpenWebUI, or any MCP client.
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
- Download
mcp-ambari-api-<version>.mcpbfrom the latest GitHub Release. - In Claude Desktop, open Settings → Extensions → Advanced settings → Install Extension….
- Select the downloaded bundle.
- Enter the Ambari host, port, username, password, cluster name, and Metrics collector settings. The password is declared as a sensitive field.
- 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:
- Call
list_ambari_metric_appsto discover valid app IDs. - Call
list_common_metrics_catalogorlist_ambari_metrics_metadatato find an exact metric name. - Call
query_ambari_metricswith an explicitapp_idand 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
.envandmcp-config.json.http.localoutside 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.12or 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:
REMOTE_AUTH_ENABLEin.env.- Whether
REMOTE_SECRET_KEYis set. - Whether
mcp-config.json.http.localstill contains the placeholder. - Whether its bearer token matches the server secret.
- 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
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.