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](INSTALL_FROM_SOURCE.md)

---

Option 1: PyPI Installation (Recommended for Quick Start)

Install from PyPI

# Install the MCP server

pip install awx-mcp-server

Verify installation

python -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.git cd awx-mcp-server/awx-mcp-python/server

Create virtual environment

python -m venv venv source venv/bin/activate # Windows: .\venv\Scripts\Activate.ps1

Install in editable mode

pip install -e .

Verify

python -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 stack

docker-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

Install

pip install -e .

Configure AWX environment (interactive)

awx-mcp-server env list

Start server

awx-mcp-server start --host 0.0.0.0 --port 8000

CLI Usage

# List job templates

awx-mcp-server templates list

Launch job

awx-mcp-server jobs launch "Deploy App" --extra-vars '{"env":"prod"}'

Monitor job

awx-mcp-server jobs get 123 awx-mcp-server jobs stdout 123

Manage projects

awx-mcp-server projects list awx-mcp-server projects update "My Project"

List inventories

awx-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 templates

curl http://localhost:8000/api/v1/job-templates \ -H "X-API-Key: awx_mcp_xxxxx"

Launch job

curl -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 status

curl http://localhost:8000/api/v1/jobs/123 \ -H "X-API-Key: awx_mcp_xxxxx"

Get job output

curl 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()

Usage

chatbot = 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 AsyncApp

import httpx

app = AsyncApp(token="[PopNx MCP ตัดค่าที่หน้าตาเหมือนกุญแจออก]") 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