ansible-mcp-server

Ansible MCP Server

A Model Context Protocol (MCP) server that enables AI assistants to manage infrastructure using Ansible and Terraform.

Features

• 58 Infrastructure Management Tools

  • Ansible playbook creation and execution
  • Terraform infrastructure provisioning
  • Hardware discovery and inventory
  • Security scanning and auditing
  • Service deployment from catalog
  • Network device management
  • Environment management (test/staging/production)

• AI-Optimized Design

  • Flexible playbook creation accepting YAML strings
  • Comprehensive error handling
  • Context persistence between sessions
  • Dynamic tool loading for services

• Cross-Platform Support

  • Linux server deployment
  • Windows client support via SSE proxy
  • Remote server management

Quick Start

Prerequisites

• Node.js 16+
• Ansible 2.9+
• Terraform (optional)

Installation

# Clone the repository
git clone https://github.com/yourusername/ansible-mcp-server.git
cd ansible-mcp-server

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings

# Run the server
npm start

For Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "ansible": {
      "command": "node",
      "args": ["/path/to/ansible-mcp-server/src/index.js"],
      "env": {
        "PROXMOX_HOST": "your-proxmox-host",
        "PROXMOX_USER": "root@pam",
        "PROXMOX_PASSWORD": "your-password"
      }
    }
  }
}

Windows Users

For Windows Claude Desktop, use the SSE proxy:

1. Deploy the MCP server to a Linux host
2. Run the SSE server on the Linux host
3. Configure Claude Desktop to use the Windows client

See Windows Setup Guide for details.

Available Tools

Ansible Tools

• create-playbook-flexible - Create playbooks with YAML strings or objects
• ansible-playbook - Run Ansible playbooks
• ansible-task - Run ad-hoc Ansible tasks
• ansible-role - Execute Ansible roles
• validate-playbook - Validate playbook syntax
• create-role-structure - Generate Ansible role directories

Infrastructure Tools

• hardware-scan - Comprehensive hardware discovery
• storage-analysis - Storage and SMART health analysis
• network-interfaces - Network adapter discovery
• discover-proxmox - Discover Proxmox VMs
• generate-inventory - Create Ansible inventories

Security Tools

• security-quick-scan - Quick security assessment
• security-scan-ports - Port scanning
• security-check-passwords - Password policy audit
• security-audit-accounts - User account audit
• security-check-ssh - SSH configuration audit

Service Management

• browse-services - Browse service catalog
• deploy-service - Deploy services from catalog
• list-environments - List deployment environments
• deploy-to-environment - Deploy with environment protection

Documentation

• Integration Guide
• Hardware Inventory Guide
• Claude Playbook Fix
• Modular Tools System

Testing

Run the comprehensive feature test suite:

# Run tests in development environment
npm test

# Test specific environments
npm run test:dev      # Development
npm run test:qa       # QA
npm run test:staging  # Staging
npm run test:prod     # Production

# Verbose output for debugging
npm run test:verbose

Our feature tests validate complete VM lifecycle workflows including:

• VM creation from Proxmox templates
• Service installation (Jenkins, etc.)
• Service verification and management
• VM deletion and cleanup
• MCP context management

See Testing Guidelines for detailed information.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built for use with Claude and other AI assistants
• Uses the Model Context Protocol
• Powered by Ansible and Terraform