io.github.SurgeX-Labs/awx-mcp-server
Control AWX/Ansible Tower through natural language - 49 tools for automation
Ask AI about io.github.SurgeX-Labs/awx-mcp-server
Powered by Claude Β· Grounded in docs
I know everything about io.github.SurgeX-Labs/awx-mcp-server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
| Method | Best For | Installation |
|---|---|---|
| π¦ PyPI (pip) | Quick install, production use | pip install awx-mcp-server |
| π§ From Source | Customization, development, enterprise forks | Clone from GitHub, edit code |
| π³ Docker | Containerized deployment, teams | docker run surgexlabs/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 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="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 environmentsenv_test- Test connection to AWX environmentenv_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 IDjob_launch- Launch job from templatejob_cancel- Cancel running jobjob_stdout- Get job output/logsjob_events- Get job events (playbook tasks)
Projects
list_projects- List all projectsproject_update- Update project from SCM
Inventories
list_inventories- List all inventoriesget_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:
- User types
@awx list templatesin Copilot Chat - Extension sends MCP request to local server via stdio
- MCP server calls AWX REST API
- Results returned to Copilot Chat
- 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:
- Client (chatbot/CLI) sends HTTP request with API key
- FastAPI server authenticates request
- Server calls AWX API via composite client
- Results returned as JSON
- 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 server
pip install -e .
awx-mcp-server start
Production - Docker
cd server
docker-compose up -d
Includes: Server, Prometheus, Grafana
Production - Kubernetes
cd server/deployment/helm
helm 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 repository
git clone https://github.com/your-org/awx-mcp.git
cd awx-mcp/awx-mcp-python
# Install shared package (for VS Code extension)
cd shared
pip install -e ".[dev]"
# Install server
cd ../server
pip install -e ".[dev]"
# Install extension dependencies
cd ../vscode-extension
npm install
# Run tests
cd ../tests
pytest -v
Running Tests
# Server tests
cd server
pytest tests/ -v --cov
# Integration tests
cd tests
pytest test_mcp_integration.py -v
Building VS Code Extension
cd vscode-extension
npm 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/endpointawx_mcp_request_duration_seconds- Request latencyawx_mcp_active_connections- Active connections per tenantawx_mcp_tool_calls_total- MCP tool invocationsawx_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:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- 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 EnvironmentCtrl+Shift+PβAWX: Test ConnectionCtrl+Shift+PβAWX: Switch Environment- In Copilot Chat:
@awx <your command>
Web Server CLI Commands
awx-mcp-server start # Start HTTP server
awx-mcp-server env list # List environments
awx-mcp-server templates list # List templates
awx-mcp-server jobs launch "Template" # Launch job
awx-mcp-server jobs get 123 # Get job details
awx-mcp-server projects list # List projects
awx-mcp-server inventories list # List inventories
Web Server API Endpoints
POST /api/keys # Create API key
GET /api/v1/environments # List environments
GET /api/v1/job-templates # List templates
POST /api/v1/jobs/launch # Launch job
GET /api/v1/jobs/{id} # Get job
GET /api/v1/jobs/{id}/stdout # Get output
GET /api/v1/projects # List projects
GET /api/v1/inventories # List inventories
GET /health # Health check
GET /prometheus-metrics # Metrics
GET /docs # API documentation
Made with β€οΈ for AWX automation and AI integration
