Awx Mcp Server

AWX MCP - AI-Powered AWX/AAP/Ansible Automation

Industry-standard MCP server for AWX/AAP/Ansible Tower automation

The AWX MCP Server connects AWX, Ansible Automation Platform (AAP), and Ansible Tower to AI tools, giving AI agents and assistants the ability to manage job templates, launch and monitor jobs, manage inventories and projects, and automate infrastructure workflows through natural language interactions.

Designed for developers who want to integrate their AI tools with AWX/AAP/Tower automation capabilities.

✨ Supports AWX (open source), AAP (Red Hat), and Ansible Tower (legacy) - same API, same features!

🎯 Usage Patterns

Primary: MCP Server (Industry Standard) ⭐ RECOMMENDED

Standard MCP implementation using STDIO transport (like Postman MCP, Claude MCP)

Use Case: AI assistants (GitHub Copilot, Claude, Cursor) + AWX automation

Features:

• ✅ Works with any MCP client (Copilot, Claude, Cursor, Windsurf, etc.)
• ✅ Industry standard pattern (STDIO transport)
• ✅ Simple installation: pip install git+https://github.com/USERNAME/awx-mcp-server.git
• ✅ Portable across all MCP-compatible tools
• ✅ 18+ AWX operations (templates, jobs, projects, inventories)

Best For: AI-powered automation, natural language AWX control, any MCP client

Optional: VS Code Extension (UI Enhancement)

Optional UI features for VS Code users

Use Case: VS Code users who want additional UI (sidebar views, tree providers)

Features:

• ✅ Sidebar with AWX instances, jobs, metrics
• ✅ Tree view of AWX resources
• ✅ Configuration webview
• ✅ Auto-configures MCP (or respects manual setup)

Best For: VS Code users wanting rich UI alongside MCP functionality

🚀 Quick Start

Installation Methods

You have three ways to install and run the AWX MCP Server:

→ For customization and running from your own repository, see INSTALL_FROM_SOURCE.md

Option 1: PyPI Installation (Recommended for Quick Start)

Install from PyPI

# Install the MCP serverpip install awx-mcp-server
# Verify installationpython -m awx_mcp_server --version

Configure for VS Code

Edit VS Code settings.json (Ctrl+, → Search "chat.mcp"):

{  "mcpServers": {    "awx": {      "command": "python",      "args": ["-m", "awx_mcp_server"],      "env": {        "AWX_BASE_URL": "https://your-awx.com"      },      "secrets": {        "AWX_TOKEN": "your-awx-token"      }    }  }}

Restart VS Code and the MCP server will be available in Copilot Chat.

Option 2: Install from Source (For Customization)

Perfect for: Forking, customization, enterprise deployments, contributing

Quick install:

# Clone the repository (or your fork)git clone https://github.com/SurgeX-Labs/awx-mcp-server.gitcd awx-mcp-server/awx-mcp-python/server
# Create virtual environmentpython -m venv venvsource venv/bin/activate  # Windows: .\venv\Scripts\Activate.ps1
# Install in editable modepip install -e .
# Verifypython -m awx_mcp_server --version

VS Code configuration (use venv Python):

{  "mcpServers": {    "awx": {      "command": "/path/to/awx-mcp-server/awx-mcp-python/server/venv/bin/python",      "args": ["-m", "awx_mcp_server"],      "env": {        "AWX_BASE_URL": "https://your-awx.com"      },      "secrets": {        "AWX_TOKEN": "your-token"      }    }  }}

📖 Full Guide: See INSTALL_FROM_SOURCE.md for:

• Forking the repository
• Making customizations to the code
• Running from your own fork/repository
• Building custom Docker images from source
• Enterprise deployment and CI/CD

Option 3: Remote Server Mode (Team/Enterprise)

Prerequisites

• Python 3.10+
• AWX/Ansible Tower instance
• (Optional) Docker or Kubernetes

Quick Start with Docker

cd awx-mcp-python/server
# Start server with monitoring stackdocker-compose up -d
# Server available at:# - API: http://localhost:8000# - Docs: http://localhost:8000/docs# - Metrics: http://localhost:8000/prometheus-metrics# - Prometheus: http://localhost:9090# - Grafana: http://localhost:3000

Quick Start with Python

cd awx-mcp-python/server
# Installpip install -e .
# Configure AWX environment (interactive)awx-mcp-server env list
# Start serverawx-mcp-server start --host 0.0.0.0 --port 8000

CLI Usage

# List job templatesawx-mcp-server templates list
# Launch jobawx-mcp-server jobs launch "Deploy App" --extra-vars '{"env":"prod"}'
# Monitor jobawx-mcp-server jobs get 123awx-mcp-server jobs stdout 123
# Manage projectsawx-mcp-server projects listawx-mcp-server projects update "My Project"
# List inventoriesawx-mcp-server inventories list

REST API Usage

# Create API key (first time)curl -X POST http://localhost:8000/api/keys \  -H "Content-Type: application/json" \  -d '{"name": "chatbot", "tenant_id": "team1", "expires_days": 90}'
# List job templatescurl http://localhost:8000/api/v1/job-templates \  -H "X-API-Key: awx_mcp_xxxxx"
# Launch jobcurl -X POST http://localhost:8000/api/v1/jobs/launch \  -H "X-API-Key: awx_mcp_xxxxx" \  -H "Content-Type: application/json" \  -d '{"template_name": "Deploy App", "extra_vars": {"env": "prod"}}'
# Get job statuscurl http://localhost:8000/api/v1/jobs/123 \  -H "X-API-Key: awx_mcp_xxxxx"
# Get job outputcurl http://localhost:8000/api/v1/jobs/123/stdout \  -H "X-API-Key: awx_mcp_xxxxx"

Kubernetes Deployment

cd server/deployment/helm
helm install awx-mcp-server . \  --set replicaCount=3 \  --set autoscaling.enabled=true \  --set taskPods.enabled=true

See: server/README.md for detailed guide

🎨 Integration Examples

Integrate with Custom Chatbot

import httpx
class AWXChatbot:    def __init__(self, api_key: str, base_url: str = "http://localhost:8000"):        self.api_key = api_key        self.base_url = base_url        self.headers = {"X-API-Key": api_key}        async def handle_message(self, user_message: str):        """Process user message and call AWX API"""        if "list templates" in user_message.lower():            return await self.list_templates()        elif "launch" in user_message.lower():            template_name = self.extract_template_name(user_message)            return await self.launch_job(template_name)        elif "job status" in user_message.lower():            job_id = self.extract_job_id(user_message)            return await self.get_job(job_id)        async def list_templates(self):        async with httpx.AsyncClient() as client:            response = await client.get(                f"{self.base_url}/api/v1/job-templates",                headers=self.headers            )            return response.json()        async def launch_job(self, template_name: str, extra_vars: dict = None):        async with httpx.AsyncClient() as client:            response = await client.post(                f"{self.base_url}/api/v1/jobs/launch",                headers=self.headers,                json={"template_name": template_name, "extra_vars": extra_vars}            )            return response.json()        async def get_job(self, job_id: int):        async with httpx.AsyncClient() as client:            response = await client.get(                f"{self.base_url}/api/v1/jobs/{job_id}",                headers=self.headers            )            return response.json()
# Usagechatbot = AWXChatbot(api_key="awx_mcp_xxxxx")response = await chatbot.handle_message("list all job templates")

Integrate with Slack Bot

from slack_bolt.async_app import AsyncAppimport httpx
app = AsyncApp(token="xoxb-your-token")awx_api_key = "awx_mcp_xxxxx"awx_base_url = "http://localhost:8000"
@app.message("awx")async def handle_awx_command(message, say):    text = message['text']        if "launch" in text:        # Extract template name from message        template = extract_template(text)                # Call AWX API        async with httpx.AsyncClient() as client:            response = await client.post(                f"{awx_base_url}/api/v1/jobs/launch",                headers={"X-API-Key": awx_api_key},                json={"template_name": template}            )            job = response.json()                await say(f"✅ Job launched! ID: {job['id']}, Status: {job['status']}")

🔧 Available AWX Operations

Both VS Code extension and web server support all 16 operations:

Environment Management

• env_list - List all configured AWX environments
• env_test - Test connection to AWX environment
• env_get_active - Get currently active environment

Job Templates

• list_job_templates - List all job templates (with filtering)
• get_job_template - Get template details by name/ID

Jobs

• list_jobs - List all jobs (filter by status, date)
• get_job - Get job details by ID
• job_launch - Launch job from template
• job_cancel - Cancel running job
• job_stdout - Get job output/logs
• job_events - Get job events (playbook tasks)

Projects

• list_projects - List all projects
• project_update - Update project from SCM

Inventories

• list_inventories - List all inventories
• get_inventory - Get inventory details

📦 Project Structure

awx-mcp-python/├── vscode-extension/          # VS Code extension with GitHub Copilot│   ├── src/                   # Extension TypeScript source│   ├── package.json           # Extension manifest│   ├── README.md              # Extension guide│   └── CHANGELOG.md││├── server/                    # Standalone web server│   ├── src/awx_mcp_server/│   │   ├── cli.py             # CLI commands (468 lines)│   │   ├── http_server.py     # FastAPI REST API│   │   ├── mcp_server.py      # MCP server integration│   │   ├── monitoring.py      # Prometheus metrics│   │   ├── task_pods.py       # Kubernetes task pods│   │   ├── clients/           # AWX clients (self-contained)│   │   ├── storage/           # Config & credentials│   │   └── domain/            # Models & exceptions│   ├── deployment/│   │   ├── docker-compose.yml # Docker Compose stack│   │   ├── Dockerfile         # Container image│   │   └── helm/              # Kubernetes Helm chart│   ├── pyproject.toml│   └── README.md│└── tests/                     # Shared test suite    ├── test_*.py    └── conftest.py

🏗️ Architecture

VS Code Extension Architecture

┌─────────────────┐│   VS Code IDE   ││                 ││  ┌───────────┐  │     stdio      ┌──────────────┐│  │  GitHub   │──┼────transport───▶│  MCP Server  ││  │  Copilot  │  │    (local)     │   (shared)   ││  │   Chat    │◀─┼────────────────│   16 Tools   ││  └───────────┘  │                └──────────────┘│                 │                        ││  ┌───────────┐  │                        ││  │ @awx Chat │  │                        ││  │Participant│  │                        ▼│  └───────────┘  │                 ┌──────────────┐└─────────────────┘                 │     AWX      │                                    │   Instance   │                                    └──────────────┘

Flow:

1. User types @awx list templates in Copilot Chat
2. Extension sends MCP request to local server via stdio
3. MCP server calls AWX REST API
4. Results returned to Copilot Chat
5. AI formats response naturally

Web Server Architecture

┌──────────────┐      REST API       ┌──────────────┐│   Chatbot    │────────────────────▶│  FastAPI     ││  /Custom App │   (HTTP/JSON)       │   Server     │└──────────────┘                     └──────────────┘                                            │┌──────────────┐      REST API       ││   Slack Bot  │────────────────────▶│└──────────────┘                     │                                     │┌──────────────┐         CLI         ││   Terminal   │────────────────────▶││   Scripts    │   (commands)        │└──────────────┘                     │                                     │                              ┌──────┴───────┐                              │              │                              │   Clients    │                              │  REST + CLI  │                              │              │                              └──────┬───────┘                                     │                                     ▼                              ┌──────────────┐                              │     AWX      │                              │   Instance   │                              └──────────────┘

Flow:

1. Client (chatbot/CLI) sends HTTP request with API key
2. FastAPI server authenticates request
3. Server calls AWX API via composite client
4. Results returned as JSON
5. Client formats for end user (Slack, terminal, etc.)

🔒 Security

VS Code Extension

• Credentials stored in VS Code secure storage
• Local server only (no network exposure)
• Environment-based isolation

Web Server

• API key authentication (SHA-256 hashed)
• Multi-tenant isolation
• Configurable key expiration
• HTTPS recommended for production
• Environment variables for secrets

🚢 Deployment Options

For VS Code Extension

• Install extension from .vsix file
• MCP server runs automatically when VS Code starts
• No additional infrastructure needed

For Web Server

Development

cd serverpip install -e .awx-mcp-server start

Production - Docker

cd serverdocker-compose up -d

Includes: Server, Prometheus, Grafana

Production - Kubernetes

cd server/deployment/helmhelm install awx-mcp-server . \  --set autoscaling.enabled=true \  --set taskPods.enabled=true \  --set ingress.enabled=true

Features:

• Horizontal Pod Autoscaling (HPA)
• Task pods (ephemeral Job per operation)
• Prometheus monitoring
• Ingress support

🛠️ Development

Prerequisites

• Python 3.10+
• Node.js 18+ (for VS Code extension)
• Docker (optional)
• Kubernetes cluster (optional)

Setup Development Environment

# Clone repositorygit clone https://github.com/your-org/awx-mcp.gitcd awx-mcp/awx-mcp-python
# Install shared package (for VS Code extension)cd sharedpip install -e ".[dev]"
# Install servercd ../serverpip install -e ".[dev]"
# Install extension dependenciescd ../vscode-extensionnpm install
# Run testscd ../testspytest -v

Running Tests

# Server testscd serverpytest tests/ -v --cov
# Integration testscd testspytest test_mcp_integration.py -v

Building VS Code Extension

cd vscode-extensionnpm run package# Generates awx-mcp-*.vsix file

📊 Monitoring (Web Server)

Access monitoring dashboards:

• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (admin/admin)
• Metrics Endpoint: http://localhost:8000/prometheus-metrics

Available Metrics

• awx_mcp_requests_total - Total requests by tenant/endpoint
• awx_mcp_request_duration_seconds - Request latency
• awx_mcp_active_connections - Active connections per tenant
• awx_mcp_tool_calls_total - MCP tool invocations
• awx_mcp_errors_total - Error count by type

📚 Documentation

Installation & Setup

• Install from PyPI - Quick install with pip install awx-mcp-server
• Install from Source - Fork, customize, and run from your own repository
• OS Compatibility - Windows, macOS, and Linux installation and configuration

Platform Support

• AAP Support Guide - Complete guide for Ansible Automation Platform, AWX, and Ansible Tower

Deployment Architectures

• Deployment Architecture - Single-user vs Team/Enterprise deployment options
• Remote Deployment Guide - Docker, Kubernetes, and cloud deployment
• Dual-Mode Quick Start - Quick reference for choosing deployment mode

Advanced Features (Planned)

• Vault Integration - HashiCorp Vault, AWS Secrets Manager, Azure Key Vault support (v2.0.0)
• Implementation Status - Current features and roadmap

Additional Resources

• MCP Copilot Setup - VS Code MCP configuration
• Quick Reference - Common commands and examples
• AWX MCP Query Reference - Natural language query examples

🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Code Style

• Python: Follow PEP 8, use type hints
• TypeScript: Follow ESLint rules
• Write tests for new features
• Update documentation

📄 License

MIT License - see LICENSE file

🆘 Support

• Issues: https://github.com/your-org/awx-mcp/issues
• Discussions: https://github.com/your-org/awx-mcp/discussions
• Documentation: See README files in subdirectories

🎉 Quick Reference

VS Code Extension Commands

• Ctrl+Shift+P → AWX: Configure Environment
• Ctrl+Shift+P → AWX: Test Connection
• Ctrl+Shift+P → AWX: Switch Environment
• In Copilot Chat: @awx <your command>

Web Server CLI Commands

awx-mcp-server start                    # Start HTTP serverawx-mcp-server env list                 # List environmentsawx-mcp-server templates list           # List templatesawx-mcp-server jobs launch "Template"   # Launch jobawx-mcp-server jobs get 123             # Get job detailsawx-mcp-server projects list            # List projectsawx-mcp-server inventories list         # List inventories

Web Server API Endpoints

POST   /api/keys                         # Create API keyGET    /api/v1/environments              # List environmentsGET    /api/v1/job-templates             # List templatesPOST   /api/v1/jobs/launch               # Launch jobGET    /api/v1/jobs/{id}                 # Get jobGET    /api/v1/jobs/{id}/stdout          # Get outputGET    /api/v1/projects                  # List projectsGET    /api/v1/inventories               # List inventoriesGET    /health                           # Health checkGET    /prometheus-metrics               # MetricsGET    /docs                             # API documentation

Made with ❤️ for AWX automation and AI integration