MCP-Ambari-API
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| AMBARI_HOST | No | Host address for the Ambari server | |
| AMBARI_PASS | No | Password for Ambari server authentication (e.g., "admin") | |
| AMBARI_PORT | No | Port number for the Ambari server | 8080 |
| AMBARI_USER | No | Username for Ambari server authentication (e.g., "admin") | |
| FASTMCP_HOST | No | Host address for HTTP transport | |
| FASTMCP_PORT | No | Port number for HTTP transport (also enables streamable-http mode when set) | |
| FASTMCP_TYPE | No | Transport type (stdio or streamable-http) | |
| AMBARI_LOG_LEVEL | No | Logging level for the MCP server (DEBUG, INFO, WARNING, ERROR) | |
| AMBARI_CLUSTER_NAME | No | Name of the target Ambari cluster (e.g., "TEST-AMBARI") |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Apache Ambari (Hadoop) cluster operations through the Ambari REST API: cluster, service, component, and host status; service and component start/stop/restart; configuration lookup; request and task tracking; users; current and historical alerts; Ambari Metrics (AMS) time series; and HDFS capacity reports.
Scope
Every tool call is a real request to the configured Ambari server and cluster (AMBARI_CLUSTER_NAME unless a tool accepts cluster_name). Use tools for facts; never guess, simulate, or invent results, and do not tell the user to check the Ambari UI or run curl instead.
The server only reads live Ambari state and runs service operations. Generic Hadoop theory, tuning advice, log analysis, installs, and data deletion are out of scope; say so and offer a concrete status query.
Call only the tools needed; avoid repeating the same lookup.
Reporting results
Report what the tool returned. Never claim success after an error, an empty response, or a partial result; quote the error.
Start/stop/restart tools submit an Ambari request; accepted is not completed. Show the returned request ID near the top (
Request ID: <id>, orUnknownif missing; never fabricate one) and point to get_request_status / get_request_tasks for progress.
Changing state
Run start/stop/restart only when the user explicitly asks for that action on a named service, component, or host. If the target is ambiguous ("restart it"), ask first.
*_all_services tools affect the whole cluster. Use them only when the user clearly asks for all services, confirm before running, and warn that live cluster state will change and may take several minutes.
If a required value (service, host, component, request ID) is missing or unclear, ask or look it up with a read tool (get_cluster_services, list_hosts, get_active_requests) instead of guessing.
Time ranges
For relative times ("yesterday", "last week"), call get_alerts_history with include_time_context=true, compute epoch-millisecond from_timestamp/to_timestamp from the returned current time, then call again with those values.
Metrics
query_ambari_metrics needs an explicit app_id and exact metric names. If unsure, find them first with list_ambari_metric_apps, list_common_metrics_catalog (search=), or list_ambari_metrics_metadata.
app_id mapping: Ambari Server=ambari_server, NameNode=namenode, DataNode=datanode, NodeManager=nodemanager, ResourceManager=resourcemanager, host-level=HOST. hostnames is optional.
Keep numbers distinct: configured values (dump_configurations), capacity (hdfs_dfadmin_report), and measured time series (query_ambari_metrics) are different things. State units, time window, and hosts. If no datapoints are returned, say so; never estimate.
Large results
Narrow before listing everything: dump_configurations with config_type, filter, service_filter, or summarize=true; get_alerts_history with filters, limit, page_size, and start_page; get_request_tasks with status_filter (e.g. "not:COMPLETED", "FAILED") and host_filter. Say when output is truncated or only one page was shown.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| extensions | {
"io.modelcontextprotocol/ui": {}
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| dump_configurationsC | Unified configuration introspection tool (supersedes get_configurations & list_configurations & dump_all_configurations). |
| get_cluster_infoA | Retrieves basic information for an Ambari cluster. [Tool Role]: Dedicated tool for real-time retrieval of overall status and basic information for an Ambari cluster. [Core Functions]:
[Required Usage Scenarios]:
Returns: Cluster basic information (success: formatted info, failure: English error message) |
| get_active_requestsA | Retrieves currently active (in progress) requests/operations in an Ambari cluster. Shows running operations, in-progress tasks, pending requests. [Tool Role]: Dedicated tool for monitoring currently running Ambari operations [Core Functions]:
[Required Usage Scenarios]:
Returns: Active requests information (success: active request list, failure: error message) |
| get_cluster_servicesA | Retrieves the list of services with status in an Ambari cluster. [Tool Role]: Dedicated tool for real-time retrieval of all running services and basic status information in an Ambari cluster [Core Functions]:
[Required Usage Scenarios]:
[Absolutely Prohibited Scenarios]:
Returns: Cluster service list with status information (success: service list with status, failure: error message) |
| get_service_statusA | Retrieves the status information for a specific service in an Ambari cluster. [Tool Role]: Dedicated tool for real-time retrieval of specific service status and state information [Core Functions]:
[Required Usage Scenarios]:
|
| get_service_componentsB | Retrieves detailed components information for a specific service in the Ambari cluster. [Tool Role]: Dedicated tool for retrieving service component details and host assignments. [Core Functions]:
[Required Usage Scenarios]:
|
| get_service_detailsA | Retrieves detailed status and configuration information for a specific service in the Ambari cluster. [Tool Role]: Dedicated tool for retrieving comprehensive service details, including state, components, and configuration. [Core Functions]:
[Required Usage Scenarios]:
|
| start_all_servicesA | Starts all services in an Ambari cluster (equivalent to "Start All" in Ambari Web UI). [Tool Role]: Dedicated tool for bulk starting all services in the cluster, automating mass startup. [Core Functions]:
[Required Usage Scenarios]:
Returns: Start operation result (success: request info, failure: English error message) |
| stop_all_servicesA | Stops all services in an Ambari cluster (equivalent to "Stop All" in Ambari Web UI). [Tool Role]: Dedicated tool for bulk stopping all services in the cluster, automating mass shutdown. [Core Functions]:
[Required Usage Scenarios]:
Returns: Stop operation result (success: request info, failure: English error message) |
| start_serviceA | Starts a specific service in the Ambari cluster. [Tool Role]: Dedicated tool for automated start of Ambari services, ensuring safe and monitored startup. [Core Functions]:
[Required Usage Scenarios]:
|
| stop_serviceA | Stops a specific service in the Ambari cluster. [Tool Role]: Dedicated tool for automated stop of Ambari services, ensuring safe and monitored shutdown. [Core Functions]:
[Required Usage Scenarios]:
|
| get_request_statusA | Retrieves the status and progress of a specific Ambari request operation. [Tool Role]: Dedicated tool for real-time tracking and reporting of Ambari request status. [Core Functions]:
[Required Usage Scenarios]:
|
| get_request_tasksA | Retrieves task-level details for a specific Ambari request (host-by-host breakdown). [Tool Role]: Provides granular, per-host task information for an Ambari request, going beyond the summary level offered by get_request_status. [Core Functions]:
[Required Usage Scenarios]:
|
| restart_serviceA | Restarts a specific service in an Ambari cluster (stop then start). [Tool Role]: Dedicated tool for automated restart of Ambari services, ensuring safe stop and start sequence. [Core Functions]:
[Required Usage Scenarios]:
|
| start_host_componentA | Starts a specific component on a specific host in the Ambari cluster. [Tool Role]: Dedicated tool for starting individual host-level components, enabling fine-grained control without affecting other hosts or the overall service. [Core Functions]:
[Required Usage Scenarios]:
|
| stop_host_componentA | Stops a specific component on a specific host in the Ambari cluster. [Tool Role]: Dedicated tool for stopping individual host-level components, enabling fine-grained control without affecting other hosts or the overall service. [Core Functions]:
[Required Usage Scenarios]:
|
| restart_host_componentA | Restarts a specific component on a specific host in the Ambari cluster (stop then start). [Tool Role]: Dedicated tool for restarting individual host-level components, enabling fine-grained control without affecting other hosts or the overall service. [Core Functions]:
[Required Usage Scenarios]:
|
| restart_all_servicesA | Restarts all services in the Ambari cluster (stop all, then start all). [Tool Role]: Dedicated tool for automated bulk restart of all Ambari services, ensuring safe stop and start sequence. [Core Functions]:
[Required Usage Scenarios]:
Returns: Bulk restart operation result (success: English completion message, failure: English error message) - Success: "All services restart operation completed successfully." - Failure: "Error: ..." with details |
| list_hostsA | Retrieves the list of hosts in the Ambari cluster. [Tool Role]: Dedicated tool for listing all hosts registered in the Ambari cluster. [Core Functions]:
[Required Usage Scenarios]:
Returns: List of hosts (success: formatted list, failure: error message) |
| get_host_detailsA | Retrieves detailed information for a specific host or all hosts in the Ambari cluster. [Tool Role]: Dedicated tool for retrieving comprehensive host details including metrics, hardware info, and components. [Core Functions]:
[Required Usage Scenarios]:
|
| list_usersA | List all users in the Ambari system. Returns a formatted list of all users with their basic information. |
| get_userB | Get detailed information about a specific user. |
| get_alerts_historyA | Retrieve current alerts or alert history from Ambari cluster. [Tool Role]: Unified tool for retrieving both current/active alert status and historical alert events from Ambari cluster [Core Functions]:
[Required Usage Scenarios]:
|
| get_current_alertsA | Retrieve current alerts from Ambari cluster. DEPRECATED: This function is deprecated in favor of get_alerts_history with mode="current". This wrapper is maintained for backward compatibility. |
| list_ambari_metrics_metadataC | Retrieve metric metadata from Ambari Metrics service with optional filters. |
| list_common_metrics_catalogC | List supported metrics per appId (exact names only). |
| list_ambari_metric_appsC | Return discovered AMS appIds, optionally with metric counts. |
| hdfs_dfadmin_reportC | Produce a DFSAdmin-style capacity and DataNode report using Ambari metrics. |
| query_ambari_metricsC | Fetch time-series metrics (exact metric names only) from Ambari Metrics. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 29 tools
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.
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.
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.
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.