bsahane/ansible-adv-mcp-server

Ansible MCP Server

A comprehensive Model Context Protocol (MCP) Server that enables AI assistants to manage infrastructure using Ansible. This server provides intelligent parsing, execution, and management of Ansible repositories with support for enterprise features and future AWX/AAP integration.

Features

🔧 Infrastructure Management

• Ansible Repository Parsing: Deep understanding of ansible.cfg, inventories, group_vars, host_vars, roles, and collections
• Multi-Repository Support: Manage multiple Ansible repositories simultaneously
• Playbook Management: Create, validate, and execute Ansible playbooks with flexible YAML input
• Hardware Discovery: Comprehensive hardware scanning and inventory generation
• Security Auditing: Security scanning, port scanning, password policy audits

🤖 AI-Optimized Design

• Flexible Input: Accept YAML strings, objects, and structured data
• Comprehensive Error Handling: Detailed error reporting and recovery mechanisms
• Context Persistence: Maintain session state and context between operations
• Dynamic Tool Loading: Extensible architecture for adding new tools and services

🚀 Cross-Platform Support

• Containerized Deployment: Docker-based deployment for consistency and scalability
• Linux Server Deployment: Primary target for server infrastructure
• Remote Server Management: Secure remote server management capabilities

🛠️ MCP Tools

Git Management Tools

• clone-repository - Clone remote Ansible repositories to local projects
• pull-repository - Pull updates from configured remote repositories
• remove-repository - Remove configured repositories from projects

Ansible Core Tools

• create-playbook-flexible - Create playbooks with YAML strings or objects
• ansible-playbook - Execute playbooks with --check and direct execution modes
• ansible-task - Execute ad-hoc Ansible tasks
• ansible-role - Execute existing roles, create new roles, manage dependencies
• ansible-collection - Install and manage Ansible collections
• validate-playbook - Validate playbook syntax and best practices
• create-role-structure - Generate standard Ansible role directories

Infrastructure Tools

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

Security Tools

• security-quick-scan - Quick security assessment
• security-scan-ports - Network port scanning and analysis
• security-check-passwords - Password policy audit and enforcement
• security-audit-accounts - User account auditing and management
• security-check-ssh - SSH configuration security audit

Service Management Tools

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

Quick Start

Prerequisites

• Node.js 18+
• Docker and Docker Compose (for containerized deployment)
• Ansible Core 2.15+ (for local development)
• Git 2.30+

Installation

Using Docker (Recommended)

1. Clone the repository:

git clone <repository-url>
cd ansible-mcp-server

2. Copy environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Start with Docker Compose:

# Production deployment
docker-compose up -d

# Development with hot reload
docker-compose --profile dev up -d ansible-mcp-dev

# With PostgreSQL
docker-compose --profile postgres up -d

Local Development

1. Install dependencies:

npm install

2. Copy environment variables:

cp .env.example .env

3. Build and start:

npm run build
npm start

# Or for development with hot reload
npm run dev

Configuration

The server uses environment variables for configuration. See .env.example for all available options.

Key Configuration Options

• DB_TYPE: Database type (sqlite or postgresql)
• DB_CONNECTION: Database connection string
• ANSIBLE_CONFIG: Path to ansible.cfg file
• ANSIBLE_INVENTORY: Default inventory file or directory
• REPOSITORIES_PATH: Directory for cloned repositories
• LOG_LEVEL: Logging level (error, warn, info, debug)

Usage

MCP Client Integration

The server implements the Model Context Protocol and can be used with any MCP-compatible client:

{
  "mcpServers": {
    "ansible-mcp-server": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "LOG_LEVEL": "info",
        "DB_TYPE": "sqlite",
        "DB_CONNECTION": "./data/ansible-mcp.db"
      }
    }
  }
}

Example Tool Usage

Clone an Ansible Repository

{
  "name": "clone-repository",
  "arguments": {
    "url": "https://github.com/example/ansible-repo.git",
    "name": "my-infrastructure",
    "branch": "main",
    "credentials": {
      "type": "token",
      "token": "ghp_xxxxxxxxxxxx"
    }
  }
}

Create and Execute a Playbook

{
  "name": "create-playbook-flexible",
  "arguments": {
    "content": "---\n- name: Install nginx\n  hosts: webservers\n  tasks:\n    - name: Install nginx package\n      apt:\n        name: nginx\n        state: present",
    "path": "./playbooks/install-nginx.yml",
    "validate": true
  }
}

{
  "name": "ansible-playbook",
  "arguments": {
    "playbookPath": "./playbooks/install-nginx.yml",
    "inventory": "./inventory/production",
    "options": {
      "checkMode": true,
      "diff": true,
      "limit": "webservers"
    }
  }
}

Perform Hardware Discovery

{
  "name": "hardware-scan",
  "arguments": {
    "hosts": "all",
    "inventory": "./inventory/production",
    "includeStorage": true,
    "includeNetwork": true
  }
}

Architecture

Core Components

1. MCP Server Core: TypeScript-based MCP server implementation
2. Ansible Engine: Python-based Ansible execution engine
3. Repository Manager: Git and Ansible repository management
4. Discovery Engine: Hardware and infrastructure discovery
5. Security Scanner: Security auditing and scanning tools
6. Service Catalog: Templated service deployment system

Technology Stack

• Primary Language: TypeScript (MCP Server), Python (Ansible Engine)
• Database: SQLite (default), PostgreSQL (enterprise)
• Containerization: Docker with multi-stage builds
• Logging: Winston with structured logging
• Validation: Joi for schema validation

Development

Project Structure

src/
├── core/           # Core MCP server and tool registry
├── services/       # Business logic services
├── tools/          # MCP tool implementations
├── types/          # TypeScript type definitions
├── utils/          # Utility functions
└── test/           # Test files

Building

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

Docker Development

# Build Docker image
npm run docker:build

# Run in container
npm run docker:run

# Development with hot reload
docker-compose --profile dev up

Security

Security Features

• Secure credential storage and management
• Role-based access control (RBAC)
• Audit logging for all operations
• Network security best practices
• Container security scanning

Security Best Practices

1. Use SSH keys instead of passwords for Git authentication
2. Enable audit logging in production
3. Run containers as non-root user
4. Use secrets management for sensitive data
5. Regularly update dependencies and base images

Performance

Performance Requirements

• Sub-second response time for basic operations
• Concurrent execution of multiple playbooks
• Scalable to 1000+ managed nodes
• Efficient memory usage in containerized environments

Optimization Tips

1. Use SQLite for single-instance deployments
2. Use PostgreSQL for multi-instance deployments
3. Configure appropriate ANSIBLE_FORKS for your environment
4. Use inventory caching for large infrastructures
5. Monitor resource usage and adjust container limits

Troubleshooting

Common Issues

Server Won't Start

• Check environment variables in .env file
• Ensure database is accessible
• Verify Node.js version (18+ required)
• Check log files for detailed error messages

Ansible Commands Fail

• Verify Ansible is installed and accessible
• Check inventory file permissions
• Validate SSH connectivity to target hosts
• Review Ansible configuration (ansible.cfg)

Repository Clone Fails

• Verify Git credentials are correct
• Check network connectivity
• Ensure sufficient disk space
• Review repository URL format

Debug Mode

Enable debug logging for detailed troubleshooting:

export LOG_LEVEL=debug
npm start

Or in Docker:

environment:
  - LOG_LEVEL=debug

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run linting and tests
6. Submit a pull request

Development Guidelines

• Follow TypeScript best practices
• Add JSDoc comments for public APIs
• Write unit tests for new features
• Update documentation for user-facing changes
• Use conventional commit messages

License

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

Future Enhancements

Phase 2: Enterprise Features

• AWX/Ansible Automation Platform integration
• Enterprise authentication (LDAP, SAML)
• Advanced workflow orchestration
• Custom dashboard and reporting

Phase 3: Advanced Intelligence

• AI-powered playbook optimization
• Predictive infrastructure monitoring
• Automated remediation workflows
• Cost optimization recommendations

Support

For issues and questions:

1. Check the troubleshooting section
2. Search existing GitHub issues
3. Create a new issue with detailed information
4. Join our Discord community

Acknowledgments

• Ansible for the powerful automation platform
• Model Context Protocol for the MCP specification
• TypeScript for type-safe development
• Docker for containerization support