Ambari MCP Server

A Model Context Protocol (MCP) server for Apache Ambari, built with the TypeScript SDK. This server provides tools to interact with Ambari clusters through the MCP protocol.

Overview

This MCP server allows AI assistants and other MCP clients to interact with Apache Ambari clusters by exposing common Ambari REST API operations as MCP tools.

Features

Cluster Management: Get cluster information, create clusters
Service Management: List and get details of cluster services
Host Management: List and get details of cluster hosts
Alert Management: Manage alert targets
Secure Authentication: Basic authentication with Ambari server
Configurable: Environment-based configuration
Type-Safe: Built with TypeScript for better reliability

Available Tools

Cluster Operations

ambari_clusters_getclusters - Returns all clusters
ambari_clusters_getcluster - Returns information about a specific cluster
ambari_clusters_createcluster - Creates a new cluster

Service Operations

ambari_services_getservices - Get all services for a cluster
ambari_services_getservice - Get details of a specific service
ambari_services_getservicestate - Get detailed state information for a specific service
ambari_services_startservice - Start a specific service on the cluster
ambari_services_stopservice - Stop a specific service on the cluster

Service Restart & Configuration Management

ambari_services_getserviceswithstaleconfigs - Get services and components that have stale configurations requiring restart
ambari_services_gethostcomponentswithstaleconfigs - Get host components that need restart due to stale configurations
ambari_services_restartservice - Restart a specific service on the cluster (supports rolling restart)
ambari_services_restartcomponents - Restart specific components that have stale configurations
ambari_services_getrollingrestartstatus - Get the status of rolling restart operations for services

Service Maintenance Mode Management

ambari_services_enablemaintenancemode - Enable maintenance mode for a service or component
ambari_services_disablemaintenancemode - Disable maintenance mode for a service or component

Service Check Operations

ambari_services_runservicecheck - Run service check for a specific service to verify it is working correctly
ambari_services_isservicechecksupported - Check if service check is supported for a specific service in the stack
ambari_services_getservicecheckstatus - Get the status of recent service check operations for a service

Host Operations

ambari_hosts_gethosts - Returns a collection of all hosts
ambari_hosts_gethost - Returns information about a single host

Alert Operations

ambari_alerts_gettargets - Returns all alert targets
ambari_alerts_getalerts - Get all alerts for a cluster with filtering options
ambari_alerts_getalertsummary - Get alert summary in grouped format for a cluster
ambari_alerts_getalertdetails - Get details for a specific alert definition
ambari_alerts_getalertdefinitions - Get all alert definitions for a cluster
ambari_alerts_updatealertdefinition - Update an alert definition (enable/disable or modify properties)

Alert Group Management

ambari_alerts_getalertgroups - Get all alert groups for a cluster
ambari_alerts_createalertgroup - Create a new alert group
ambari_alerts_updatealertgroup - Update an existing alert group
ambari_alerts_deletealertgroup - Delete an alert group
ambari_alerts_duplicatealertgroup - Duplicate an existing alert group with a new name
ambari_alerts_adddefinitiontogroup - Add an alert definition to an alert group
ambari_alerts_removedefinitionfromgroup - Remove an alert definition from an alert group

Alert Notification Management

ambari_alerts_getnotifications - Get all alert notification targets
ambari_alerts_createnotification - Create a new alert notification target
ambari_alerts_updatenotification - Update an existing alert notification target
ambari_alerts_deletenotification - Delete an alert notification target
ambari_alerts_addnotificationtogroup - Add a notification target to an alert group
ambari_alerts_removenotificationfromgroup - Remove a notification target from an alert group

Alert Settings

ambari_alerts_savealertsettings - Save cluster-level alert settings (like repeat tolerance)

Installation

Clone or copy this server to your local machine
Install dependencies:
```
npm install
```
Install dev dependencies (if not already installed):
```
npm install typescript @types/node --save-dev
```

Configuration

Copy the example environment file:
```
cp .env.example .env
```

Edit the .env file with your Ambari server details:

AMBARI_BASE_URL=http://your-ambari-server:8080/api/v1
AMBARI_USERNAME=admin
AMBARI_PASSWORD=admin
TIMEOUT_MS=30000

Building

Build the TypeScript code:

npm run build

Usage

As a Standalone Server

Run the server directly:

npm start

With MCP Clients

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "ambari": {
      "command": "node",
      "args": ["/path/to/ambari-mcp-server/dist/index.js"]
    }
  }
}

Other MCP Clients

The server communicates via stdio and follows the MCP protocol specification.

Development

Project Structure

ambari-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (after build)
├── .env.example         # Environment configuration template
├── package.json         # Node.js dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

Development Commands

npm run build - Compile TypeScript to JavaScript
npm run dev - Build and run the server
npm start - Run the compiled server

Adding New Tools

Add the tool definition to the AMBARI_TOOLS array
Implement the tool executor in the toolExecutors object
Update this README with the new tool documentation

Example:

// Add to AMBARI_TOOLS
{
  name: 'ambari_new_operation',
  description: 'Description of the new operation',
  inputSchema: {
    type: 'object',
    properties: {
      // Define input parameters
    },
    required: ['requiredParam']
  }
}

// Add to toolExecutors
ambari_new_operation: async (args) => {
  return executeAmbariRequest('GET', '/new-endpoint', args);
}

Error Handling

The server includes comprehensive error handling:

Network timeouts and connection errors
HTTP error responses from Ambari
Invalid tool parameters
Authentication failures

Errors are returned as MCP error responses with appropriate error codes and messages.

Security Considerations

Store sensitive credentials in environment variables
Use HTTPS for Ambari server connections in production
Implement proper authentication and authorization
Consider network security between MCP client and server

Troubleshooting

Common Issues

Connection Refused: Check if Ambari server is running and accessible
Authentication Failed: Verify username and password in .env
Timeout Errors: Increase TIMEOUT_MS value
Build Errors: Ensure TypeScript and dependencies are installed

Debug Mode

Set environment variable DEBUG=1 for verbose logging:

DEBUG=1 npm start

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

ISC License - see package.json for details

MCP Servers