MCP Ambari API - Apache Hadoop Cluster Management Automation

🚀 Automate Apache Ambari operations with AI/LLM: Conversational control for Hadoop cluster management, service monitoring, configuration inspection, and precise Ambari Metrics queries via Model Context Protocol (MCP) tools.

License: MIT Python Docker Pulls smithery badge Verified on MSeeP BuyMeACoffee

Deploy to PyPI with tag PyPI PyPI - Downloads

Architecture & Internal (DeepWiki)

Ask DeepWiki

📋 Overview

MCP Ambari API is a powerful Model Context Protocol (MCP) server that enables seamless Apache Ambari cluster management through natural language commands. Built for DevOps engineers, data engineers, and system administrators who work with Hadoop ecosystems.

Features

Docuement for Airflow REST-API

Topics

apache-ambari hadoop-cluster mcp-server cluster-automation devops-tools big-data infrastructure-management ai-automation llm-tools python-mcp

Example Queries - Cluster Info/Status

Go to More Example Queries

Example: Querying Ambari Cluster(1)

Example: Querying Ambari Cluster(2)

🚀 QuickStart Guide /w Docker

Note: The following instructions assume you are using the streamable-http mode for MCP Server.

Flow Diagram of Quickstart/Tutorial

Flow Diagram of Quickstart/Tutorial

1. Prepare Ambari Cluster (Test Target)

To set up a Ambari Demo cluster, follow the guide at: Install Ambari 3.0 with Docker

Example: Ambari Demo Cluster

2. Run Docker-Compose

Start the MCP-Server, MCPO(MCP-Proxy for OpenAPI), and OpenWebUI.

  1. Ensure Docker and Docker Compose are installed on your system.
  2. Clone this repository and navigate to its root directory.
  3. Set up environment configuration: 
    # Copy environment template and configure your settings
cp .env.example .env
# Edit .env with your Ambari cluster information
  4. Configure your Ambari connection in .env file: 
    # Ambari cluster connection
AMBARI_HOST=host.docker.internal
AMBARI_PORT=7070
AMBARI_USER=admin
AMBARI_PASS=admin
AMBARI_CLUSTER_NAME=TEST-AMBARI

# Ambari Metrics (AMS) collector
AMBARI_METRICS_HOST=host.docker.internal
AMBARI_METRICS_PORT=16188
AMBARI_METRICS_PROTOCOL=http
AMBARI_METRICS_TIMEOUT=15
   
# (Optional) Enable authentication for streamable-http mode
# Recommended for production environments
REMOTE_AUTH_ENABLE=false
REMOTE_SECRET_KEY=your-secure-secret-key-here
  5. Run: 
    docker-compose up -d

Example: MCPO-Proxy

3. Registering the Tool in OpenWebUI

📌 Note: Web-UI configuration instructions are based on OpenWebUI v0.6.22. Menu locations and settings may differ in newer versions.

  1. logging in to OpenWebUI with an admin account
  2. go to “Settings” → “Tools” from the top menu.
  3. Enter the mcp-ambari-api Tool address (e.g., http://localhost:8000/mcp-ambari-api) to connect MCP Tools with your Ambari cluster.

4. More Examples: Using MCP Tools to Query Ambari Cluster

Below is an example screenshot showing how to query the Ambari cluster using MCP Tools in OpenWebUI:

Example Query - Cluster Configuration Review & Recommendations

Example: Querying Ambari Cluster(2)

Example Query - Restart HDFS Service

Example: Querying Ambari Cluster(3) Example: Querying Ambari Cluster(3)

📈 Metrics & Trends

Live Metric Catalog (via AMS metadata)

🔍 Ambari Metrics Query Requirements (Exact-Match Workflow)

Recent updates removed natural-language metric guessing in favor of deterministic, catalog-driven lookups. Keep the following rules in mind when you (or an LLM agent) call query_ambari_metrics:

  1. Always pass an explicit app_id. If it is missing or unsupported, the tool returns a list of valid appIds and aborts so you can choose one manually.
  2. Specify exact metric names. Use list_common_metrics_catalog(app_id="<target>", search="keyword"), list_ambari_metric_apps (to discover appIds), or the ambari-metrics://catalog/<appId> resource to browse the live per-app metric set and copy the identifier (e.g., jvm.JvmMetrics.MemHeapUsedM).
  3. Host-scope behavior: When hostnames is omitted the API returns cluster-wide aggregates. Provide one or more hosts (comma-separated) to focus on specific nodes.
  4. No fuzzy matches. The server now calls Ambari exactly as requested. If the metric is wrong or empty, Ambari will simply return no datapoints—double-check the identifier via /ws/v1/timeline/metrics/metadata.

Example invocation:

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

For multi-metric lookups, pass a comma-separated list of exact names. Responses document any auto-applied host filters so you can copy/paste them into subsequent requests.

🐛 Usage & Configuration

This MCP server supports two connection modes: stdio (traditional) and streamable-http (Docker-based). You can configure the transport mode using CLI arguments or environment variables.

Configuration Priority: CLI arguments > Environment variables > Default values

CLI Arguments

Environment Variables

Variable Description Default Project Default
PYTHONPATH Python module search path for MCP server imports - /app/src
MCP_LOG_LEVEL Server logging verbosity (DEBUG, INFO, WARNING, ERROR) INFO INFO
FASTMCP_TYPE MCP transport protocol (stdio for CLI, streamable-http for web) stdio streamable-http
FASTMCP_HOST HTTP server bind address (0.0.0.0 for all interfaces) 127.0.0.1 0.0.0.0
FASTMCP_PORT HTTP server port for MCP communication 8000 8000
REMOTE_AUTH_ENABLE Enable Bearer token authentication for streamable-http mode
Default: false (if undefined, empty, or null)		 false false
REMOTE_SECRET_KEY Secret key for Bearer token authentication
Required when REMOTE_AUTH_ENABLE=true		 - your-secret-key-here
AMBARI_HOST Ambari server hostname or IP address 127.0.0.1 host.docker.internal
AMBARI_PORT Ambari server port number 8080 8080
AMBARI_USER Username for Ambari server authentication admin admin
AMBARI_PASS Password for Ambari server authentication admin admin
AMBARI_CLUSTER_NAME Name of the target Ambari cluster TEST-AMBARI TEST-AMBARI
DOCKER_EXTERNAL_PORT_OPENWEBUI Host port mapping for Open WebUI container 8080 3001
DOCKER_EXTERNAL_PORT_MCP_SERVER Host port mapping for MCP server container 8080 18001
DOCKER_EXTERNAL_PORT_MCPO_PROXY Host port mapping for MCPO proxy container 8000 8001

Note: AMBARI_CLUSTER_NAME serves as the default target cluster for operations when no specific cluster is specified. All environment variables can be configured via the .env file.

Transport Selection Logic:

Configuration Priority: CLI arguments > Environment variables > Default values

Transport Selection Logic:

Environment Setup

# 1. Clone the repository
git clone https://github.com/call518/MCP-Ambari-API.git
cd MCP-Ambari-API

# 2. Set up environment configuration
cp .env.example .env

# 3. Configure your Ambari connection in .env file
AMBARI_HOST=your-ambari-host
AMBARI_PORT=your-ambari-port  
AMBARI_USER=your-username
AMBARI_PASS=your-password
AMBARI_CLUSTER_NAME=your-cluster-name

🔐 Security & Authentication

Bearer Token Authentication

For streamable-http mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.

Configuration

Enable Authentication:

# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=your-secure-secret-key-here

Or via CLI:

python -m mcp_ambari_api --type streamable-http --auth-enable --secret-key your-secure-secret-key-here

Security Levels

  1. stdio mode (Default): Local-only access, no authentication needed
  2. streamable-http + REMOTE_AUTH_ENABLE=false/undefined: Remote access without authentication ⚠️ NOT RECOMMENDED for production
  3. streamable-http + REMOTE_AUTH_ENABLE=true: Remote access with Bearer token authentication ✅ RECOMMENDED for production

🔒 Default Policy: REMOTE_AUTH_ENABLE defaults to false if undefined, empty, or null. This ensures the server starts even without explicit authentication configuration.

Client Configuration

When authentication is enabled, MCP clients must include the Bearer token in the Authorization header:

{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http",
      "url": "http://your-server:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

Security Best Practices

Error Handling

When authentication fails, the server returns:

Method 1: Local MCP (transport=”stdio”)

{
  "mcpServers": {
    "mcp-ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "host.docker.internal",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "TEST-AMBARI",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Method 2: Remote MCP (transport=”streamable-http”)

On MCP-Client Host:

{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http",
      "url": "http://localhost:18001/mcp"
    }
  }
}

With Bearer Token Authentication (Recommended for production):

{
  "mcpServers": {
    "mcp-ambari-api": {
      "type": "streamable-http", 
      "url": "http://localhost:18001/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

Example usage: Claude-Desktop

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-ambari-api": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "localhost",
        "AMBARI_PORT": "7070",
        "AMBARI_USER": "admin",
        "AMBARI_PASS": "admin",
        "AMBARI_CLUSTER_NAME": "TEST-AMBARI",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Example: Claude-Desktop(3)

(Option) Configure Multiple Ambari Cluster

{
  "mcpServers": {
    "Ambari-Cluster-A": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "a.foo.com",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin-user",
        "AMBARI_PASS": "admin-pass",
        "AMBARI_CLUSTER_NAME": "AMBARI-A",
        "MCP_LOG_LEVEL": "INFO"
      }
    },
    "Ambari-Cluster-B": {
      "command": "uvx",
      "args": ["--python", "3.12", "mcp-ambari-api"],
      "env": {
        "AMBARI_HOST": "b.bar.com",
        "AMBARI_PORT": "8080",
        "AMBARI_USER": "admin-user",
        "AMBARI_PASS": "admin-pass",
        "AMBARI_CLUSTER_NAME": "AMBARI-B",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Remote Access with Authentication (Claude Desktop):

{
  "mcpServers": {
    "mcp-ambari-api-remote": {
      "type": "streamable-http",
      "url": "http://your-server-ip:18001/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-secret-key-here"
      }
    }
  }
}

🎯 Core Features & Capabilities

Service Operations

Configuration Management

Monitoring & Alerting

Administration

Available MCP Tools

This MCP server provides the following tools for Ambari cluster management:

Cluster Management

Service Management

Configuration Tools

Breaking Change: get_configurations and list_configurations were removed in favor of this single, more capable tool.

Host Management

User Management

Alert Management

🤝 Contributing & Support

How to Contribute

Technologies Used

Dev Env.

🛠️ Adding Custom Tools

After you’ve thoroughly explored the existing functionality, you might want to add your own custom tools for specific monitoring or management needs. This MCP server is designed for easy extensibility.

Step-by-Step Guide

1. Add Helper Functions (Optional)

Add reusable data functions to src/mcp_ambari_api/functions.py:

async def get_your_custom_data(target_resource: str = None) -> List[Dict[str, Any]]:
    """Your custom data retrieval function."""
    # Example implementation - adapt to your Ambari service
    endpoint = f"/clusters/{AMBARI_CLUSTER_NAME}/your_custom_endpoint"
    if target_resource:
        endpoint += f"/{target_resource}"
    
    response_data = await make_ambari_request(endpoint)
    
    if response_data is None or "items" not in response_data:
        return []
    
    return response_data["items"]

2. Create Your MCP Tool

Add your tool function to src/mcp_ambari_api/mcp_main.py:

@mcp.tool()
@log_tool
async def get_your_custom_analysis(limit: int = 50, target_name: Optional[str] = None) -> str:
    """
    [Tool Purpose]: Brief description of what your tool does
    
    [Core Functions]:
    - Feature 1: Data aggregation and analysis
    - Feature 2: Resource monitoring and insights
    - Feature 3: Performance metrics and reporting
    
    [Required Usage Scenarios]:
    - When user asks "your specific analysis request"
    - Your business-specific monitoring needs
    
    Args:
        limit: Maximum results (1-100)
        target_name: Target resource/service name (optional)
    
    Returns:
        Formatted analysis results (success: formatted data, failure: English error message)
    """
    try:
        limit = max(1, min(limit, 100))  # Always validate input
        
        results = await get_your_custom_data(target_resource=target_name)
        
        if not results:
            return f"No custom analysis data found{' for ' + target_name if target_name else ''}."
        
        # Apply limit
        limited_results = results[:limit]
        
        # Format output
        result_lines = [
            f"Custom Analysis Results{' for ' + target_name if target_name else ''}",
            "=" * 50,
            f"Found: {len(limited_results)} items (total: {len(results)})",
            ""
        ]
        
        for i, item in enumerate(limited_results, 1):
            # Customize this formatting based on your data structure
            name = item.get("name", "Unknown")
            status = item.get("status", "N/A")
            result_lines.append(f"[{i}] {name}: {status}")
        
        return "\n".join(result_lines)
        
    except Exception as e:
        return f"Error: Exception occurred while retrieving custom analysis - {str(e)}"

3. Update Imports

Add your helper function to the imports section in src/mcp_ambari_api/mcp_main.py:

from mcp_ambari_api.functions import (
    format_timestamp,
    format_single_host_details,
    make_ambari_request,
    # ... existing imports ...
    get_your_custom_data,  # Add your new function here
)

Add your tool description to src/mcp_ambari_api/prompt_template.md for better AI recognition:

### Custom Analysis Tools

**get_your_custom_analysis**
- "Show me custom analysis results"
- "Get custom analysis for target_name"
- "Display custom monitoring data"
- 📋 **Features**: Custom data aggregation, resource monitoring, performance insights

5. Test Your Tool

# Local testing with MCP Inspector
./run-mcp-inspector-local.sh

# Or test with Docker environment
docker-compose up -d
docker-compose logs -f mcp-server

# Test with natural language queries:
# "Show me custom analysis results"
# "Get custom analysis for my_target"

Important Notes

Example Use Cases

❓ Frequently Asked Questions

Q: What Ambari versions are supported?

A: Ambari 2.7+ is recommended. Earlier versions may work but are not officially tested.

Q: Can I use this with cloud-managed Hadoop clusters?

A: Yes, as long as Ambari API endpoints are accessible, it works with on-premise, cloud, and hybrid deployments.

Q: How do I troubleshoot connection issues?

A: Check your AMBARI_HOST, AMBARI_PORT, and network connectivity. Enable debug logging with MCP_LOG_LEVEL=DEBUG.

Q: How does this compare to Ambari Web UI?

A: This provides programmatic access via AI/LLM commands, perfect for automation, scripting, and integration with modern DevOps workflows.

Contributing

🤝 Got ideas? Found bugs? Want to add cool features?

We’re always excited to welcome new contributors! Whether you’re fixing a typo, adding a new monitoring tool, or improving documentation - every contribution makes this project better.

Ways to contribute:

Pro tip: The codebase is designed to be super friendly for adding new tools. Check out the existing @mcp.tool() functions in mcp_main.py and follow the Adding Custom Tools guide above.

📄 License

This project is licensed under the MIT License.