{
"markdown": "# AWX MCP - AI-Powered AWX/AAP/Ansible Automation\n\n**Industry-standard MCP server for AWX/AAP/Ansible Tower automation**\n\nThe 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.\n\n**Designed for developers who want to integrate their AI tools with AWX/AAP/Tower automation capabilities.**\n\n**β¨ Supports AWX (open source), AAP (Red Hat), and Ansible Tower (legacy) - same API, same features!**\n\n---\n\n## π― Usage Patterns\n\n### Primary: MCP Server (Industry Standard) β RECOMMENDED\n\n![\"MCP](\"https://img.shields.io/badge/MCP-Server-green?logo=python\")
\n\n**Standard MCP implementation using STDIO transport (like Postman MCP, Claude MCP)**\n\n**Use Case**: AI assistants (GitHub Copilot, Claude, Cursor) + AWX automation\n\n**Features**:\n- β
Works with any MCP client (Copilot, Claude, Cursor, Windsurf, etc.)\n- β
Industry standard pattern (STDIO transport)\n- β
Simple installation: `pip install git+https://github.com/USERNAME/awx-mcp-server.git`\n- β
Portable across all MCP-compatible tools\n- β
18+ AWX operations (templates, jobs, projects, inventories)\n\n**Best For**: AI-powered automation, natural language AWX control, any MCP client\n\n---\n\n### Optional: VS Code Extension (UI Enhancement)\n\n![\"VS](\"https://img.shields.io/badge/VS%20Code-Optional-007ACC?logo=visualstudiocode\")
\n\n**Optional UI features for VS Code users**\n\n**Use Case**: VS Code users who want additional UI (sidebar views, tree providers)\n\n**Features**:\n- β
Sidebar with AWX instances, jobs, metrics\n- β
Tree view of AWX resources\n- β
Configuration webview\n- β
Auto-configures MCP (or respects manual setup)\n\n**Best For**: VS Code users wanting rich UI alongside MCP functionality\n\n---\n\n## π Quick Start\n\n### Installation Methods\n\nYou have **three ways** to install and run the AWX MCP Server:\n\n| Method | Best For | Installation |\n|--------|----------|--------------|\n| **π¦ PyPI (pip)** | Quick install, production use | `pip install awx-mcp-server` |\n| **π§ From Source** | Customization, development, enterprise forks | Clone from GitHub, edit code |\n| **π³ Docker** | Containerized deployment, teams | `docker run surgexlabs/awx-mcp-server` |\n\n**β For customization and running from your own repository, see [INSTALL_FROM_SOURCE.md](INSTALL_FROM_SOURCE.md)**\n\n---\n\n### Option 1: PyPI Installation (Recommended for Quick Start)\n\n#### Install from PyPI\n\n```bash\n# Install the MCP server\npip install awx-mcp-server\n\n# Verify installation\npython -m awx_mcp_server --version\n```\n\n#### Configure for VS Code\n\n**Edit VS Code settings.json** (`Ctrl+,` β Search \"chat.mcp\"):\n\n```json\n{\n \"mcpServers\": {\n \"awx\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"awx_mcp_server\"],\n \"env\": {\n \"AWX_BASE_URL\": \"https://your-awx.com\"\n },\n \"secrets\": {\n \"AWX_TOKEN\": \"your-awx-token\"\n }\n }\n }\n}\n```\n\n**Restart VS Code** and the MCP server will be available in Copilot Chat.\n\n---\n\n### Option 2: Install from Source (For Customization)\n\n**Perfect for**: Forking, customization, enterprise deployments, contributing\n\n**Quick install**:\n```bash\n# Clone the repository (or your fork)\ngit clone https://github.com/SurgeX-Labs/awx-mcp-server.git\ncd awx-mcp-server/awx-mcp-python/server\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # Windows: .\\venv\\Scripts\\Activate.ps1\n\n# Install in editable mode\npip install -e .\n\n# Verify\npython -m awx_mcp_server --version\n```\n\n**VS Code configuration** (use venv Python):\n```json\n{\n \"mcpServers\": {\n \"awx\": {\n \"command\": \"/path/to/awx-mcp-server/awx-mcp-python/server/venv/bin/python\",\n \"args\": [\"-m\", \"awx_mcp_server\"],\n \"env\": {\n \"AWX_BASE_URL\": \"https://your-awx.com\"\n },\n \"secrets\": {\n \"AWX_TOKEN\": \"your-token\"\n }\n }\n }\n}\n```\n\n**π Full Guide**: See [INSTALL_FROM_SOURCE.md](INSTALL_FROM_SOURCE.md) for:\n- Forking the repository\n- Making customizations to the code\n- Running from your own fork/repository\n- Building custom Docker images from source\n- Enterprise deployment and CI/CD\n\n---\n\n### Option 3: Remote Server Mode (Team/Enterprise)\n\n#### Prerequisites\n- Python 3.10+\n- AWX/Ansible Tower instance\n- (Optional) Docker or Kubernetes\n\n#### Quick Start with Docker\n\n```bash\ncd awx-mcp-python/server\n\n# Start server with monitoring stack\ndocker-compose up -d\n\n# Server available at:\n# - API: http://localhost:8000\n# - Docs: http://localhost:8000/docs\n# - Metrics: http://localhost:8000/prometheus-metrics\n# - Prometheus: http://localhost:9090\n# - Grafana: http://localhost:3000\n```\n\n#### Quick Start with Python\n\n```bash\ncd awx-mcp-python/server\n\n# Install\npip install -e .\n\n# Configure AWX environment (interactive)\nawx-mcp-server env list\n\n# Start server\nawx-mcp-server start --host 0.0.0.0 --port 8000\n```\n\n#### CLI Usage\n\n```bash\n# List job templates\nawx-mcp-server templates list\n\n# Launch job\nawx-mcp-server jobs launch \"Deploy App\" --extra-vars '{\"env\":\"prod\"}'\n\n# Monitor job\nawx-mcp-server jobs get 123\nawx-mcp-server jobs stdout 123\n\n# Manage projects\nawx-mcp-server projects list\nawx-mcp-server projects update \"My Project\"\n\n# List inventories\nawx-mcp-server inventories list\n```\n\n#### REST API Usage\n\n```bash\n# Create API key (first time)\ncurl -X POST http://localhost:8000/api/keys \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"chatbot\", \"tenant_id\": \"team1\", \"expires_days\": 90}'\n\n# List job templates\ncurl http://localhost:8000/api/v1/job-templates \\\n -H \"X-API-Key: awx_mcp_xxxxx\"\n\n# Launch job\ncurl -X POST http://localhost:8000/api/v1/jobs/launch \\\n -H \"X-API-Key: awx_mcp_xxxxx\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"template_name\": \"Deploy App\", \"extra_vars\": {\"env\": \"prod\"}}'\n\n# Get job status\ncurl http://localhost:8000/api/v1/jobs/123 \\\n -H \"X-API-Key: awx_mcp_xxxxx\"\n\n# Get job output\ncurl http://localhost:8000/api/v1/jobs/123/stdout \\\n -H \"X-API-Key: awx_mcp_xxxxx\"\n```\n\n#### Kubernetes Deployment\n\n```bash\ncd server/deployment/helm\n\nhelm install awx-mcp-server . \\\n --set replicaCount=3 \\\n --set autoscaling.enabled=true \\\n --set taskPods.enabled=true\n```\n\n**See**: [server/README.md](server/README.md) for detailed guide\n\n---\n\n## π¨ Integration Examples\n\n### Integrate with Custom Chatbot\n\n```python\nimport httpx\n\nclass AWXChatbot:\n def __init__(self, api_key: str, base_url: str = \"http://localhost:8000\"):\n self.api_key = api_key\n self.base_url = base_url\n self.headers = {\"X-API-Key\": api_key}\n \n async def handle_message(self, user_message: str):\n \"\"\"Process user message and call AWX API\"\"\"\n if \"list templates\" in user_message.lower():\n return await self.list_templates()\n elif \"launch\" in user_message.lower():\n template_name = self.extract_template_name(user_message)\n return await self.launch_job(template_name)\n elif \"job status\" in user_message.lower():\n job_id = self.extract_job_id(user_message)\n return await self.get_job(job_id)\n \n async def list_templates(self):\n async with httpx.AsyncClient() as client:\n response = await client.get(\n f\"{self.base_url}/api/v1/job-templates\",\n headers=self.headers\n )\n return response.json()\n \n async def launch_job(self, template_name: str, extra_vars: dict = None):\n async with httpx.AsyncClient() as client:\n response = await client.post(\n f\"{self.base_url}/api/v1/jobs/launch\",\n headers=self.headers,\n json={\"template_name\": template_name, \"extra_vars\": extra_vars}\n )\n return response.json()\n \n async def get_job(self, job_id: int):\n async with httpx.AsyncClient() as client:\n response = await client.get(\n f\"{self.base_url}/api/v1/jobs/{job_id}\",\n headers=self.headers\n )\n return response.json()\n\n# Usage\nchatbot = AWXChatbot(api_key=\"awx_mcp_xxxxx\")\nresponse = await chatbot.handle_message(\"list all job templates\")\n```\n\n### Integrate with Slack Bot\n\n```python\nfrom slack_bolt.async_app import AsyncApp\nimport httpx\n\napp = AsyncApp(token=\"xoxb-your-token\")\nawx_api_key = \"awx_mcp_xxxxx\"\nawx_base_url = \"http://localhost:8000\"\n\n@app.message(\"awx\")\nasync def handle_awx_command(message, say):\n text = message['text']\n \n if \"launch\" in text:\n # Extract template name from message\n template = extract_template(text)\n \n # Call AWX API\n async with httpx.AsyncClient() as client:\n response = await client.post(\n f\"{awx_base_url}/api/v1/jobs/launch\",\n headers={\"X-API-Key\": awx_api_key},\n json={\"template_name\": template}\n )\n job = response.json()\n \n await say(f\"β
Job launched! ID: {job['id']}, Status: {job['status']}\")\n```\n\n---\n\n## π§ Available AWX Operations\n\nBoth VS Code extension and web server support all 16 operations:\n\n### Environment Management\n- `env_list` - List all configured AWX environments\n- `env_test` - Test connection to AWX environment\n- `env_get_active` - Get currently active environment\n\n### Job Templates\n- `list_job_templates` - List all job templates (with filtering)\n- `get_job_template` - Get template details by name/ID\n\n### Jobs\n- `list_jobs` - List all jobs (filter by status, date)\n- `get_job` - Get job details by ID\n- `job_launch` - Launch job from template\n- `job_cancel` - Cancel running job\n- `job_stdout` - Get job output/logs\n- `job_events` - Get job events (playbook tasks)\n\n### Projects\n- `list_projects` - List all projects\n- `project_update` - Update project from SCM\n\n### Inventories\n- `list_inventories` - List all inventories\n- `get_inventory` - Get inventory details\n\n---\n\n## π¦ Project Structure\n\n```\nawx-mcp-python/\nβββ vscode-extension/ # VS Code extension with GitHub Copilot\nβ βββ src/ # Extension TypeScript source\nβ βββ package.json # Extension manifest\nβ βββ README.md # Extension guide\nβ βββ CHANGELOG.md\nβ\nβ\nβββ server/ # Standalone web server\nβ βββ src/awx_mcp_server/\nβ β βββ cli.py # CLI commands (468 lines)\nβ β βββ http_server.py # FastAPI REST API\nβ β βββ mcp_server.py # MCP server integration\nβ β βββ monitoring.py # Prometheus metrics\nβ β βββ task_pods.py # Kubernetes task pods\nβ β βββ clients/ # AWX clients (self-contained)\nβ β βββ storage/ # Config & credentials\nβ β βββ domain/ # Models & exceptions\nβ βββ deployment/\nβ β βββ docker-compose.yml # Docker Compose stack\nβ β βββ Dockerfile # Container image\nβ β βββ helm/ # Kubernetes Helm chart\nβ βββ pyproject.toml\nβ βββ README.md\nβ\nβββ tests/ # Shared test suite\n βββ test_*.py\n βββ conftest.py\n```\n\n---\n\n## ποΈ Architecture\n\n### VS Code Extension Architecture\n\n```\nβββββββββββββββββββ\nβ VS Code IDE β\nβ β\nβ βββββββββββββ β stdio ββββββββββββββββ\nβ β GitHub ββββΌββββtransportββββΆβ MCP Server β\nβ β Copilot β β (local) β (shared) β\nβ β Chat ββββΌβββββββββββββββββ 16 Tools β\nβ βββββββββββββ β ββββββββββββββββ\nβ β β\nβ βββββββββββββ β β\nβ β @awx Chat β β β\nβ βParticipantβ β βΌ\nβ βββββββββββββ β ββββββββββββββββ\nβββββββββββββββββββ β AWX β\n β Instance β\n ββββββββββββββββ\n```\n\n**Flow**:\n1. User types `@awx list templates` in Copilot Chat\n2. Extension sends MCP request to local server via stdio\n3. MCP server calls AWX REST API\n4. Results returned to Copilot Chat\n5. AI formats response naturally\n\n### Web Server Architecture\n\n```\nββββββββββββββββ REST API ββββββββββββββββ\nβ Chatbot ββββββββββββββββββββββΆβ FastAPI β\nβ /Custom App β (HTTP/JSON) β Server β\nββββββββββββββββ ββββββββββββββββ\n β\nββββββββββββββββ REST API β\nβ Slack Bot ββββββββββββββββββββββΆβ\nββββββββββββββββ β\n β\nββββββββββββββββ CLI β\nβ Terminal ββββββββββββββββββββββΆβ\nβ Scripts β (commands) β\nββββββββββββββββ β\n β\n ββββββββ΄ββββββββ\n β β\n β Clients β\n β REST + CLI β\n β β\n ββββββββ¬ββββββββ\n β\n βΌ\n ββββββββββββββββ\n β AWX β\n β Instance β\n ββββββββββββββββ\n```\n\n**Flow**:\n1. Client (chatbot/CLI) sends HTTP request with API key\n2. FastAPI server authenticates request\n3. Server calls AWX API via composite client\n4. Results returned as JSON\n5. Client formats for end user (Slack, terminal, etc.)\n\n---\n\n## π Security\n\n### VS Code Extension\n- Credentials stored in VS Code secure storage\n- Local server only (no network exposure)\n- Environment-based isolation\n\n### Web Server\n- API key authentication (SHA-256 hashed)\n- Multi-tenant isolation\n- Configurable key expiration\n- HTTPS recommended for production\n- Environment variables for secrets\n\n---\n\n## π’ Deployment Options\n\n### For VS Code Extension\n- Install extension from .vsix file\n- MCP server runs automatically when VS Code starts\n- No additional infrastructure needed\n\n### For Web Server\n\n#### Development\n```bash\ncd server\npip install -e .\nawx-mcp-server start\n```\n\n#### Production - Docker\n```bash\ncd server\ndocker-compose up -d\n```\nIncludes: Server, Prometheus, Grafana\n\n#### Production - Kubernetes\n```bash\ncd server/deployment/helm\nhelm install awx-mcp-server . \\\n --set autoscaling.enabled=true \\\n --set taskPods.enabled=true \\\n --set ingress.enabled=true\n```\nFeatures:\n- Horizontal Pod Autoscaling (HPA)\n- Task pods (ephemeral Job per operation)\n- Prometheus monitoring\n- Ingress support\n\n---\n\n## π οΈ Development\n\n### Prerequisites\n- Python 3.10+\n- Node.js 18+ (for VS Code extension)\n- Docker (optional)\n- Kubernetes cluster (optional)\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/your-org/awx-mcp.git\ncd awx-mcp/awx-mcp-python\n\n# Install shared package (for VS Code extension)\ncd shared\npip install -e \".[dev]\"\n\n# Install server\ncd ../server\npip install -e \".[dev]\"\n\n# Install extension dependencies\ncd ../vscode-extension\nnpm install\n\n# Run tests\ncd ../tests\npytest -v\n```\n\n### Running Tests\n\n```bash\n# Server tests\ncd server\npytest tests/ -v --cov\n\n# Integration tests\ncd tests\npytest test_mcp_integration.py -v\n```\n\n### Building VS Code Extension\n\n```bash\ncd vscode-extension\nnpm run package\n# Generates awx-mcp-*.vsix file\n```\n\n---\n\n## π Monitoring (Web Server)\n\nAccess monitoring dashboards:\n\n- **Prometheus**: http://localhost:9090\n- **Grafana**: http://localhost:3000 (admin/admin)\n- **Metrics Endpoint**: http://localhost:8000/prometheus-metrics\n\n### Available Metrics\n\n- `awx_mcp_requests_total` - Total requests by tenant/endpoint\n- `awx_mcp_request_duration_seconds` - Request latency\n- `awx_mcp_active_connections` - Active connections per tenant\n- `awx_mcp_tool_calls_total` - MCP tool invocations\n- `awx_mcp_errors_total` - Error count by type\n\n---\n\n## π Documentation\n\n### Installation & Setup\n- **[Install from PyPI](https://pypi.org/project/awx-mcp-server/)** - Quick install with `pip install awx-mcp-server`\n- **[Install from Source](INSTALL_FROM_SOURCE.md)** - Fork, customize, and run from your own repository\n- **[OS Compatibility](OS_COMPATIBILITY.md)** - Windows, macOS, and Linux installation and configuration\n\n### Platform Support\n- **[AAP Support Guide](AAP_SUPPORT.md)** - Complete guide for Ansible Automation Platform, AWX, and Ansible Tower\n\n### Deployment Architectures\n- **[Deployment Architecture](DEPLOYMENT_ARCHITECTURE.md)** - Single-user vs Team/Enterprise deployment options\n- **[Remote Deployment Guide](server/REMOTE_DEPLOYMENT.md)** - Docker, Kubernetes, and cloud deployment\n- **[Dual-Mode Quick Start](DUAL_MODE_QUICKSTART.md)** - Quick reference for choosing deployment mode\n\n### Advanced Features (Planned)\n- **[Vault Integration](server/VAULT_INTEGRATION.md)** - HashiCorp Vault, AWS Secrets Manager, Azure Key Vault support (v2.0.0)\n- **[Implementation Status](IMPLEMENTATION_STATUS.md)** - Current features and roadmap\n\n### Additional Resources\n- **[MCP Copilot Setup](vscode-extension/MCP_COPILOT_SETUP.md)** - VS Code MCP configuration\n- **[Quick Reference](docs/QUICKREF.md)** - Common commands and examples\n- **[AWX MCP Query Reference](AWX_MCP_QUERY_REFERENCE.md)** - Natural language query examples\n\n---\n\n## π€ Contributing\n\nWe welcome contributions! Please:\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Submit a pull request\n\n### Code Style\n- Python: Follow PEP 8, use type hints\n- TypeScript: Follow ESLint rules\n- Write tests for new features\n- Update documentation\n\n---\n\n## π License\n\nMIT License - see [LICENSE](LICENSE) file\n\n---\n\n## π Support\n\n- **Issues**: https://github.com/your-org/awx-mcp/issues\n- **Discussions**: https://github.com/your-org/awx-mcp/discussions\n- **Documentation**: See README files in subdirectories\n\n---\n\n## π Quick Reference\n\n### VS Code Extension Commands\n\n- `Ctrl+Shift+P` β `AWX: Configure Environment`\n- `Ctrl+Shift+P` β `AWX: Test Connection`\n- `Ctrl+Shift+P` β `AWX: Switch Environment`\n- In Copilot Chat: `@awx `\n\n### Web Server CLI Commands\n\n```bash\nawx-mcp-server start # Start HTTP server\nawx-mcp-server env list # List environments\nawx-mcp-server templates list # List templates\nawx-mcp-server jobs launch \"Template\" # Launch job\nawx-mcp-server jobs get 123 # Get job details\nawx-mcp-server projects list # List projects\nawx-mcp-server inventories list # List inventories\n```\n\n### Web Server API Endpoints\n\n```\nPOST /api/keys # Create API key\nGET /api/v1/environments # List environments\nGET /api/v1/job-templates # List templates\nPOST /api/v1/jobs/launch # Launch job\nGET /api/v1/jobs/{id} # Get job\nGET /api/v1/jobs/{id}/stdout # Get output\nGET /api/v1/projects # List projects\nGET /api/v1/inventories # List inventories\nGET /health # Health check\nGET /prometheus-metrics # Metrics\nGET /docs # API documentation\n```\n\n---\n\n**Made with β€οΈ for AWX automation and AI integration**\n",
"bytes": 19383,
"sha": "a0342d758e78703c61317bca6a9a6b061105ff08b9b0559b2765dc4ba0d552b6",
"repo_slug": "surgex-labs/awx-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_surgex_labs_awx_mcp_server_f51f94fb/readme"
}