ansible-mcp-server

ry-ops/ansible-mcp-server

3.2

If you are the rightful owner of ansible-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Ansible MCP Server is a Model Context Protocol server that provides comprehensive Ansible automation and configuration management capabilities as part of the Cortex automation ecosystem.

Tools
5
Resources
0
Prompts
0

Ansible MCP Server

Configuration Management Capabilities for the Cortex Ecosystem

Part of Cortex MCP Python

A Model Context Protocol (MCP) server that provides comprehensive Ansible automation and configuration management capabilities. Part of the Cortex automation ecosystem.

Features

Core Capabilities

  • Playbook Execution: Run Ansible playbooks with full parameter control
  • Ad-hoc Commands: Execute quick tasks without writing playbooks
  • Inventory Management: List and inspect inventory hosts and groups
  • Fact Gathering: Collect system information from managed hosts
  • Role Discovery: Find and inspect available Ansible roles
  • Collection Management: List and install Ansible collections
  • Vault Operations: Encrypt and decrypt sensitive data
  • Playbook Linting: Validate syntax and best practices
  • Playbook Discovery: Find available playbooks in directories
  • Variable Inspection: Extract playbook variables

Safety Features

  • Syntax Validation: Automatic playbook syntax checking before execution
  • Check Mode: Dry-run support for all operations
  • Execution Logging: Complete audit trail of all commands
  • Error Handling: Graceful error handling with detailed messages

Installation

Prerequisites

  • Python 3.10 or higher
  • Ansible 2.9+ installed and accessible in PATH
  • (Optional) ansible-lint for enhanced playbook validation

Install from PyPI

pip install ansible-mcp-server

Install from Source

git clone https://github.com/yourusername/ansible-mcp-server.git
cd ansible-mcp-server
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

Running the Server

ansible-mcp-server

The server communicates via stdio and is designed to be used with MCP clients.

Configuration with Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ansible": {
      "command": "ansible-mcp-server"
    }
  }
}

Available Tools

1. run_playbook

Execute an Ansible playbook with comprehensive options.

{
  "playbook_path": "/path/to/playbook.yml",
  "inventory": "/path/to/inventory",
  "extra_vars": {
    "env": "production",
    "version": "2.0.0"
  },
  "tags": ["deploy"],
  "check_mode": true,
  "verbose": 2
}

Parameters:

  • playbook_path (required): Path to playbook YAML file
  • inventory: Inventory file path
  • extra_vars: Variables as key-value object
  • tags: Only run specific tags
  • skip_tags: Skip specific tags
  • limit: Limit to specific hosts
  • check_mode: Dry-run mode (no changes)
  • diff: Show file changes
  • verbose: Verbosity level (0-4)

Safety: Automatically validates syntax before execution.

2. run_adhoc

Run ad-hoc Ansible commands on hosts.

{
  "hosts": "webservers",
  "module": "shell",
  "args": "uptime",
  "inventory": "/path/to/inventory",
  "become": true,
  "check_mode": false
}

Parameters:

  • hosts (required): Host pattern
  • module (required): Ansible module name
  • args: Module arguments
  • inventory: Inventory file path
  • become: Use privilege escalation
  • check_mode: Dry-run mode

3. list_inventory

List inventory hosts and groups.

{
  "inventory": "/path/to/inventory",
  "list_hosts": true,
  "graph": false
}

4. get_facts

Gather facts from hosts.

{
  "hosts": "all",
  "inventory": "/path/to/inventory",
  "gather_subset": ["network", "hardware"]
}

5. list_roles

List available Ansible roles.

{
  "roles_path": "/custom/roles/path"
}

Searches standard locations:

  • ./roles
  • ~/.ansible/roles
  • /etc/ansible/roles

6. list_collections

List installed Ansible collections.

{}

7. install_collection

Install collections from Ansible Galaxy.

{
  "collection_name": "community.general",
  "version": "5.0.0",
  "force": false
}

8. vault_encrypt

Encrypt strings or files with Ansible Vault.

{
  "content": "my_secret_password",
  "vault_password_file": "/path/to/vault_pass",
  "is_file": false
}

9. vault_decrypt

Decrypt Ansible Vault encrypted files.

{
  "file_path": "/path/to/encrypted.yml",
  "vault_password_file": "/path/to/vault_pass"
}

10. lint_playbook

Validate playbook syntax and best practices.

{
  "playbook_path": "/path/to/playbook.yml"
}

Uses ansible-lint if available, otherwise falls back to syntax check.

11. list_playbooks

Find playbooks in a directory.

{
  "directory": "/path/to/playbooks"
}

12. get_playbook_vars

Extract variables from a playbook.

{
  "playbook_path": "/path/to/playbook.yml"
}

Usage Examples

Example 1: Deploy Application with Safety Checks

# First, validate the playbook
lint_playbook({ "playbook_path": "deploy.yml" })

# Run in check mode to see what would change
run_playbook({
  "playbook_path": "deploy.yml",
  "inventory": "production",
  "check_mode": true,
  "diff": true
})

# If check looks good, run for real
run_playbook({
  "playbook_path": "deploy.yml",
  "inventory": "production",
  "extra_vars": { "version": "2.1.0" },
  "tags": ["deploy"]
})

Example 2: Quick Server Check

# Check if servers are reachable
run_adhoc({
  "hosts": "all",
  "module": "ping",
  "inventory": "production"
})

# Get system uptime
run_adhoc({
  "hosts": "webservers",
  "module": "shell",
  "args": "uptime",
  "inventory": "production"
})

Example 3: Fact Gathering and Reporting

# Gather network facts
get_facts({
  "hosts": "database_servers",
  "inventory": "production",
  "gather_subset": ["network", "hardware"]
})

Example 4: Collection Management

# List installed collections
list_collections()

# Install a new collection
install_collection({
  "collection_name": "community.docker",
  "version": "3.0.0"
})

Execution Logging

All executions are logged to ~/.ansible-mcp-server/logs/ with detailed information:

{
  "timestamp": "2025-12-09T10:30:00Z",
  "command": ["ansible-playbook", "deploy.yml", "-i", "production"],
  "result": {
    "success": true,
    "returncode": 0,
    "stdout": "...",
    "stderr": ""
  }
}

Integration with Cortex

This MCP server is part of the Cortex automation ecosystem and integrates with:

  • Cortex Masters: Development, CI/CD, and Security masters
  • Worker Orchestration: Spawned by masters for Ansible tasks
  • Knowledge Base: Records successful playbook patterns
  • Dashboard: Reports execution metrics and results

Architecture

ansible-mcp-server/
├── src/
│   └── ansible_mcp_server/
│       ├── __init__.py
│       └── server.py          # Main server implementation
├── tests/
│   ├── __init__.py
│   ├── test_server.py
│   └── test_executor.py
├── pyproject.toml
└── README.md

Key Components

  • AnsibleExecutor: Core execution engine with safety features
  • MCP Server: Tool registration and request handling
  • Logging System: Complete audit trail of operations
  • Validation Layer: Syntax checking and error prevention

Error Handling

The server provides detailed error information:

{
  "success": false,
  "error": "Playbook syntax validation failed",
  "validation_output": "ERROR! Syntax error...",
  "command": "ansible-playbook --syntax-check playbook.yml"
}

Security Considerations

  • Vault Support: Full Ansible Vault integration for secrets
  • Check Mode: Test changes before applying
  • Privilege Escalation: Explicit become flag required
  • Execution Logging: Complete audit trail
  • Syntax Validation: Prevents invalid playbooks from running

Development

Running Tests

pytest tests/

Code Quality

# Format code
black src/

# Lint
ruff check src/

# Type checking
mypy src/

Project Structure

The server follows MCP best practices:

  • Async/await for all I/O operations
  • Structured error handling
  • Comprehensive logging
  • Type hints throughout

Contributing

This server is part of the Cortex ecosystem. Contributions should:

  1. Follow existing code style (Black, Ruff)
  2. Include tests for new features
  3. Update documentation
  4. Maintain backward compatibility
  5. Include type hints

Troubleshooting

Ansible Not Found

Ensure Ansible is installed and in PATH:

ansible --version

Install if needed:

pip install ansible

Syntax Validation Fails

Check playbook syntax manually:

ansible-playbook --syntax-check playbook.yml

Collection Installation Issues

Ensure ansible-galaxy is available:

ansible-galaxy --version

Vault Operations Require Password

Provide vault password file:

{
  "vault_password_file": "/path/to/vault_pass"
}

License

MIT

Cortex Ecosystem

Part of the Cortex automation system - an AI-powered development and operations framework.

Other Cortex components:

  • cortex-core: Central coordination system
  • cortex-masters: Specialized AI agents for different domains
  • cortex-workers: Task-specific execution agents
  • cortex-dashboard: Real-time monitoring and control

Support

For issues, questions, or contributions:

Built with the Model Context Protocol (MCP) for seamless AI integration.