mcp-ansible

MCP Ansible Server

Advanced Ansible Model Context Protocol (MCP) server in Python exposing Ansible utilities for inventories, playbooks, roles, and project workflows.

Quick start

git clone https://github.com/bsahane/mcp-ansible.git
cd mcp-ansible

# Create and activate Python virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies via requirements.txt
python -m pip install -U pip
pip install -r requirements.txt

# (Optional) install the project package locally
pip install -e .

# Run the MCP server
python src/ansible_mcp/server.py

Requirements

• Python 3.10+
• macOS/Linux

Setup

cd /Users/bsahane/Developer/cursor/mcp-ansible
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install "mcp[cli]>=1.2.0" "PyYAML>=6.0.1" "ansible-core>=2.16.0"
pip install -e .

Run the server

python src/ansible_mcp/server.py

Cursor config (`/Users/bsahane/.cursor/mcp.json`)

{
  "mcpServers": {
    "ansible-mcp": {
      "command": "python",
      "args": [
        "/Users/bsahane/Developer/cursor/mcp-ansible/src/ansible_mcp/server.py"
      ],
      "env": {
        "MCP_ANSIBLE_PROJECT_ROOT": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server",
        "MCP_ANSIBLE_INVENTORY": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini",
        "MCP_ANSIBLE_PROJECT_NAME": "projectAIOPS"
      }
    }
  }
}

Claude for Desktop config

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

{
  "mcpServers": {
    "ansible-mcp": {
      "command": "python",
      "args": [
        "/Users/bsahane/Developer/cursor/mcp-ansible/src/ansible_mcp/server.py"
      ],
      "env": {
        "MCP_ANSIBLE_PROJECT_ROOT": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server",
        "MCP_ANSIBLE_INVENTORY": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini",
        "MCP_ANSIBLE_PROJECT_NAME": "projectAIOPS"
      }
    }
  }
}

Tools (names)

Core Ansible Tools:

• create-playbook: Create playbooks from YAML strings or dicts
• validate-playbook: Validate playbook syntax (ansible-playbook --syntax-check)
• ansible-playbook: Execute playbooks
• ansible-task: Run ad-hoc tasks (defaults to connection=local for localhost)
• ansible-role: Execute roles via generated temporary playbook
• create-role-structure: Scaffold role directory tree
• ansible-inventory: List inventory hosts and groups
• register-project: Register an Ansible project for easy reuse
• list-projects: Show registered projects and default
• project-playbooks: Discover playbooks under a project root
• project-run-playbook: Run a playbook using a registered project's inventory/env

Local inventory suite (no AAP/AWX):

• inventory-parse: Parse inventories (ansible.cfg-aware), return hosts/groups/hostvars
• inventory-graph: Show group/host graph
• inventory-find-host: Show a host's groups and merged vars
• ansible-ping: Ad-hoc ping module
• ansible-gather-facts: Run setup and return parsed facts
• validate-yaml: Validate YAML files with error locations
• galaxy-install: Install roles/collections from requirements
• project-bootstrap: Galaxy install + env inspection

Advanced Troubleshooting Suite:

*Foundation Tools:*

• ansible-remote-command: Execute arbitrary shell commands with enhanced output parsing
• ansible-fetch-logs: Fetch and analyze log files with pattern detection and correlation
• ansible-service-manager: Manage services with status checking and log correlation

*Intelligent Diagnostics:*

• ansible-diagnose-host: Comprehensive health assessment with scoring and recommendations
• ansible-capture-baseline: Capture system state snapshots for comparison
• ansible-compare-states: Time-travel debugging with baseline comparisons

*Automation & Self-Healing:*

• ansible-auto-heal: Intelligent automated problem resolution with safety checks

*Network & Security:*

• ansible-network-matrix: Comprehensive network connectivity testing between hosts
• ansible-security-audit: Security vulnerability assessment and compliance checking

*Performance & Monitoring:*

• ansible-health-monitor: Continuous monitoring with trend analysis and anomaly detection
• ansible-performance-baseline: Performance benchmarking and regression detection
• ansible-log-hunter: Advanced log correlation and pattern hunting across multiple sources

Environment variables (optional)

• MCP_ANSIBLE_PROJECT_ROOT: absolute project root
• MCP_ANSIBLE_INVENTORY: inventory path or directory
• MCP_ANSIBLE_PROJECT_NAME: label for env project
• MCP_ANSIBLE_ROLES_PATH: colon-separated roles paths
• MCP_ANSIBLE_COLLECTIONS_PATHS: colon-separated collections paths
• MCP_ANSIBLE_ENV_: forwarded to process env (e.g., MCP_ANSIBLE_ENV_ANSIBLE_CONFIG)

Examples (Claude Tools)

• List hosts from inventory:
  • Tool: ansible-inventory
  • Args: inventory = "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"

• Run a simple playbook:
  • Tool: ansible-playbook
  • Args:
    • playbook_path: absolute path to playbook.yml
    • inventory: "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"

• Ad-hoc ping localhost:
  • Tool: ansible-task
  • Args:
    • host_pattern: "localhost"
    • module: "ping"
    • inventory: "localhost,"

• Scaffold a role:
  • Tool: create-role-structure
  • Args:
    • base_path: "/tmp"
    • role_name: "demo_role"

• Register a project and run a project playbook:
  • Tool: register-project
    • name: "projectAIOPS"
    • root: "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server"
    • inventory: "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"
    • make_default: true
  • Tool: project-playbooks
    • project: "projectAIOPS"
  • Tool: project-run-playbook
    • playbook_path: absolute path from discovered list

Examples for local inventory suite

• Parse via ansible.cfg with multiple inventories (merges group_vars/host_vars):
  • Tool: inventory-parse
  • Args:
    • ansible_cfg_path: "/abs/path/to/ansible.cfg"
    • include_hostvars: true

• Parse a specific extensionless inventory file:
  • Tool: inventory-parse
  • Args:
    • project_root: "/abs/path/to/project"
    • inventory_paths: ["/abs/path/to/project/inventories/stage/inventory"]
    • include_hostvars: true

• Ping a group from inventory:
  • Tool: ansible-ping
  • Args:
    • project_root: "/abs/path/to/project"
    • host_pattern: "aws_mx_ext_stage"

Notes

• The server uses stdio transport. Do not print to stdout; logs go to stderr.
• Ansible connection/auth follows your local Ansible configuration.

Reference

• MCP Quickstart (Python): https://modelcontextprotocol.io/quickstart/server#python

Tool reference (detailed)

Below are all tools with short descriptions, minimal args, an example question you can ask in the MCP UI, and a sample answer.

• create-playbook: Create an Ansible playbook file from YAML string or object
  • Minimal args:

{ "playbook": [{"hosts":"all","tasks":[{"debug":{"msg":"hi"}}]}] }

• validate-playbook: Syntax check a playbook
  • Minimal args:

{ "playbook_path": "/abs/playbook.yml" }

• ansible-playbook: Run a playbook
  • Minimal args:

{ "playbook_path": "/abs/playbook.yml", "inventory": "localhost," }

• ansible-task: Run an ad‑hoc module
  • Minimal args:

{ "host_pattern": "localhost", "module": "ping", "inventory": "localhost," }

• ansible-role: Execute a role via a temporary playbook
  • Minimal args:

{ "role_name": "myrole", "hosts": "localhost", "inventory": "localhost," }

• create-role-structure: Scaffold a role directory tree
  • Minimal args:

{ "base_path": "/tmp", "role_name": "demo" }

• ansible-inventory: List hosts and groups from an inventory
  • Minimal args:

{ "inventory": "/abs/inventory" }

• register-project: Register an Ansible project for reuse
  • Minimal args:

{ "name": "proj", "root": "/abs/project", "make_default": true }

• list-projects: Show registered projects
  • Minimal args: `{}`
  • Example question: "What projects are registered and which is default?"
  • Possible answer: `{ "default": "proj", "projects": {"proj": {"root": "/abs"}} }`

• project-playbooks: Discover playbooks under a project root
  • Minimal args:

{ "project": "proj" }

• project-run-playbook: Run a playbook using project inventory/env
  • Minimal args:

{ "playbook_path": "/abs/x.yml", "project": "proj" }

• inventory-parse: Parse inventories (ansible.cfg aware, merges group_vars/host_vars)
  • Minimal args:

{ "project_root": "/abs/project", "include_hostvars": true }

• inventory-graph: Show inventory graph
  • Minimal args:

{ "project_root": "/abs/project" }

• inventory-find-host: Show a host’s groups and merged vars
  • Minimal args:

{ "project_root": "/abs/project", "host": "h1" }

• ansible-ping: Ping hosts via ad-hoc
  • Minimal args:

{ "project_root": "/abs/project", "host_pattern": "localhost" }

• ansible-gather-facts: Run setup and return facts
  • Minimal args:

{ "project_root": "/abs/project", "host_pattern": "localhost" }

• validate-yaml: Validate YAML files
  • Minimal args:

{ "paths": ["/abs/file.yml"] }

• galaxy-install: Install roles/collections from requirements
  • Minimal args:

{ "project_root": "/abs/project" }

• project-bootstrap: Bootstrap project (env info + galaxy install)
  • Minimal args:

{ "project_root": "/abs/project" }

• inventory-diff: Diff two inventories
  • Minimal args:

{ "left_project_root": "/abs/project", "right_project_root": "/abs/project" }

• ansible-test-idempotence: Run playbook twice and assert no changes second run
  • Minimal args:

{ "playbook_path": "/abs/playbook.yml", "project_root": "/abs/project" }

• galaxy-lock: Generate a lock file of installed roles/collections
  • Minimal args:

{ "project_root": "/abs/project" }

• vault-encrypt / vault-decrypt / vault-view / vault-rekey: Vault operations
  • Minimal args (encrypt):

{ "file_paths": ["/abs/group_vars/all/vault.yml"], "project_root": "/abs/project" }

Troubleshooting Suite Reference

Foundation Tools

• ansible-remote-command: Execute shell commands with enhanced parsing
  • Minimal args:

{ "host_pattern": "webserver", "command": "ps aux | grep nginx" }

• ansible-fetch-logs: Fetch and analyze log files
  • Minimal args:

{ "host_pattern": "app*", "log_paths": ["/var/log/nginx/error.log"], "analyze": true }

• ansible-service-manager: Service management with logs
  • Minimal args:

{ "host_pattern": "web", "service_name": "nginx", "action": "restart", "check_logs": true }

Intelligent Diagnostics

• ansible-diagnose-host: Comprehensive health assessment
  • Minimal args:

{ "host_pattern": "production", "checks": ["system", "network", "security"], "include_recommendations": true }

• ansible-capture-baseline: Capture system state baseline
  • Minimal args:

{ "host_pattern": "web*", "snapshot_name": "pre-deployment", "include": ["configs", "processes"] }

• ansible-compare-states: Compare against baseline
  • Minimal args:

{ "host_pattern": "web*", "baseline_snapshot_id": "snapshot_20250101_120000_abc123" }

Automation & Self-Healing

• ansible-auto-heal: Automated problem resolution
  • Minimal args:

{ "host_pattern": "database", "symptoms": ["high_memory", "disk_full"], "max_impact": "medium", "dry_run": true }

Network & Security

• ansible-network-matrix: Network connectivity testing
  • Minimal args:

{ "host_patterns": ["web*", "db*"], "check_ports": [22, 3306, 443] }

• ansible-security-audit: Security vulnerability assessment
  • Minimal args:

{ "host_pattern": "all", "audit_categories": ["packages", "permissions", "network"], "generate_report": true }

Performance & Monitoring

• ansible-health-monitor: Continuous monitoring with trends
  • Minimal args:

{ "host_pattern": "production", "monitoring_duration": 300, "metrics_interval": 30 }

• ansible-performance-baseline: Performance benchmarking
  • Minimal args:

{ "host_pattern": "web*", "benchmark_duration": 60, "store_baseline": true }

• ansible-log-hunter: Advanced log correlation
  • Minimal args:

{ "host_pattern": "app*", "search_patterns": ["ERROR", "CRITICAL"], "time_range": "1h", "correlation_window": 300 }

Key Features of Troubleshooting Suite

🎯 Intelligent Analysis

• Health Scoring: Automated scoring based on CPU, memory, disk, network, and security metrics
• Pattern Recognition: Smart analysis of log patterns, error correlations, and system anomalies
• Trend Detection: Real-time monitoring with trend analysis and predictive insights

🔧 Automated Remediation

• Symptom-to-Solution Mapping: Intelligent problem resolution based on detected symptoms
• Safety-First Approach: Graduated response with impact assessment and mandatory safety checks
• Dry-Run Mode: Preview all actions before execution for safety validation

📊 Advanced Analytics

• Baseline Comparisons: Time-travel debugging with comprehensive state comparisons
• Performance Benchmarking: Establish baselines and detect performance regressions
• Security Auditing: Comprehensive vulnerability assessment with compliance scoring

🛡️ Enterprise-Grade Safety

• Impact Controls: Configurable impact levels (low/medium/high) with approval workflows
• Audit Trails: Complete logging of all troubleshooting actions and decisions
• Rollback Capabilities: Automated reversion for failed operations

🔄 Pure Ansible Integration

• No SSH Dependencies: All operations go through Ansible's native connection framework
• Module Consistency: Uses standard Ansible modules for maximum compatibility
• Configuration Aware: Respects ansible.cfg and existing project configurations

All troubleshooting tools maintain the same safety, auditability, and Ansible-native approach while providing enterprise-grade automation capabilities.