Overview

This project implements an MCP (Model Context Protocol) server that connects large language model agents to Apache Ambari clusters through a set of callable tools. Instead of memorizing Ambari REST API details or writing imperative scripts, operators and automation agents can issue natural-language instructions that the MCP server maps to Ambari API operations. The server handles request translation, parameter validation, and Ambari authentication so LLM-based agents can perform cluster-management tasks safely and reproducibly.

The MCP server is useful for DevOps engineers and Hadoop administrators who want to prototype conversational or agent-driven workflows for common Ambari actions — for example, checking service health, starting and stopping services, restarting components, or adding hosts. By exposing Ambari operations as structured tools over MCP, the server enables chain-of-thought-free model calls and simplifies integrating LLMs into existing automation pipelines.

Features

Exposes Ambari cluster operations as MCP-compatible tools for LLM agents
Maps natural-language intents to Ambari REST API calls with parameter validation
Common Ambari actions supported: service control, cluster status, component restart, host management
Lightweight HTTP server with JSON endpoints optimized for integration with model agents
Configurable Ambari credentials and base URL via environment variables or config file
Simple CLI / curl examples to exercise tools manually during development

Installation / Configuration

Prerequisites: Python 3.8+, git, an Ambari server reachable from the MCP server host. Clone the repository, create a virtual environment, and install dependencies.

# clone repo
git clone https://github.com/call518/MCP-Ambari-API.git
cd MCP-Ambari-API

# create and activate venv (Linux/macOS)
python -m venv .venv
source .venv/bin/activate

# install
pip install -r requirements.txt

Configure connection to Ambari using environment variables or a JSON/YAML config file. Example environment variables:

export AMBARI_URL="https://ambari.example.com"
export AMBARI_USER="admin"
export AMBARI_PASS="s3cret"
export MCP_BIND_HOST="0.0.0.0"
export MCP_BIND_PORT="8080"

Example config file (config.json):

{
  "ambari": {
    "url": "https://ambari.example.com",
    "username": "admin",
    "password": "s3cret"
  },
  "server": {
    "host": "0.0.0.0",
    "port": 8080
  }
}

Run the server (example using uvicorn for an ASGI app):

uvicorn mcp_ambari.app:app --host 0.0.0.0 --port 8080 --reload

Adjust the command to your project layout if the entrypoint differs.

Available Tools / Resources

The MCP server exposes a set of tools that correspond to common Ambari operations. Each tool accepts structured input and returns JSON results. Below is a representative list; consult the running server’s /tools endpoint for the exact tool registry.

Tool name	Purpose	Parameters
get_cluster_status	Query overall cluster and services health	cluster_name (optional)
list_services	List services and their states	cluster_name (optional)
start_service	Start a service (e.g., HDFS, YARN)	cluster_name, service_name
stop_service	Stop a service	cluster_name, service_name
restart_component	Restart a specific component on a host (e.g., DATANODE)	cluster_name, component_name, host_name
add_host	Register a new host in Ambari	cluster_name, host_name, host_info
decommission_datanode	Decommission an HDFS DataNode	cluster_name, host_name

Example curl: get cluster status

curl -X POST http://localhost:8080/mcp/call \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_cluster_status","input":{"cluster_name":"my-cluster"}}'

Use Cases

Troubleshooting: “Check my-cluster and list any critical services that are down.”
The model can call get_cluster_status and list_services, returning a concise report of failing components and suggested next steps.
Rolling restart: “Perform a rolling restart of HBase regionservers.”
The agent maps this to restart_component calls across region server hosts in a controlled sequence to avoid large service disruption.
Scale out: “Add host host123.example.com to the cluster and start DataNode.”
Workflow: add_host -> configure components -> start_service/start component on the new host.
Emergency stop/start: “Stop YARN to drain the cluster, then later start it back.”
The agent performs stop_service and later start_service, including status checks in between to confirm transition states.

Concrete example — natural-language to MCP call:

Natural-language: “Restart all HDFS DataNodes on host host01.example.com.”

MCP call (JSON):

{
  "tool": "restart_component",
  "input": {
    "cluster_name": "my-cluster",
    "component_name": "DATANODE",
    "host_name": "host01.example.com"
  }
}

Response: structured JSON reflecting Ambari job status and request ID.

Security and Best Practices

Protect Ambari credentials; prefer vaults or secrets managers over plain environment variables.
Run the MCP server behind authentication and TLS; restrict which models/agents can call the MCP endpoints.
Use role-based Ambari accounts that limit destructive operations in production.
Test on a non-production cluster before automating critical operations.

Repository and further details: https://github.com/call518/MCP-Ambari-API.

MCP Server for Ambari Natural-Language Cluster Management