awx-mcp-server

Name: awx-mcp-server
Author: SurgeX-Labs

本地服务

github.com/SurgeX-Labs云与基础设施1435 周前更新

代码仓库

关于 awx-mcp-server

awx-mcp-server 将 AWX、AAP 和 Ansible Tower 自动化能力接入 AI 工具，面向需要以自然语言管理自动化任务的开发者。它提供模板、作业、项目和清单操作，并有 VS Code 扩展及独立 Web 服务模式。

主要功能

01管理作业模板并启动、监控或取消作业
02查看作业输出与事件
03列出项目并更新项目
04浏览清单及其详情
05提供 VS Code 扩展界面
06支持 Web 服务、CLI 与容器部署

适用场景

01通过 AI 客户端启动部署作业
02检查运行中作业的状态和日志
03查询 AWX 项目与清单信息
04从 CLI 或 Web 服务集成自动化操作

MCP 相关

MCP 服务通过 AWX API 向兼容客户端暴露环境、模板、作业、项目和清单操作。主要采用 stdio 传输；项目还提供 Web 服务和 CLI 作为其他接入方式。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "surgex-labs-awx": {
      "command": "uvx",
      "args": [
        "awx-mcp-server"
      ],
      "env": {
        "AWX_BASE_URL": "<AWX_BASE_URL>",
        "AWX_TOKEN": "<AWX_TOKEN>",
        "AWX_USERNAME": "<AWX_USERNAME>",
        "AWX_PASSWORD": "<AWX_PASSWORD>",
        "AWX_VERIFY_SSL": "<AWX_VERIFY_SSL>"
      }
    }
  }
}

启动命令uvx awx-mcp-server

需要配置的环境变量

AWX_BASE_URLThe base URL of your AWX/Ansible Tower instance

AWX_TOKEN密钥AWX API token for authentication

AWX_USERNAMEAWX username (alternative to token)

AWX_PASSWORD密钥AWX password (alternative to token)

AWX_VERIFY_SSLWhether to verify SSL certificates (set to false for self-signed)

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

pypiawx-mcp-server1.1.2stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

AWX MCP - AI 驱动的 AWX/AAP/Ansible 自动化

用于 AWX/AAP/Ansible Tower 自动化的行业标准 MCP 服务

AWX MCP 服务可将 AWX、Ansible Automation Platform (AAP) 和 Ansible Tower 连接到 AI 工具，让 AI Agent 和助手能够管理作业模板、启动和监控作业、管理清单和项目，并通过自然语言交互自动化基础设施工作流。

专为希望将 AI 工具与 AWX/AAP/Tower 自动化功能集成的开发者打造。

✨ 支持 AWX（开源）、AAP（Red Hat）和 Ansible Tower（旧版）——使用相同的 API，提供相同的功能！

🎯 使用模式

主要方式：MCP 服务（行业标准）⭐ 推荐

使用 STDIO 传输方式的标准 MCP 实现（类似 Postman MCP、Claude MCP）

适用场景：AI 助手（GitHub Copilot、Claude、Cursor）+ AWX 自动化

功能：

✅ 适用于任何 MCP 客户端（Copilot、Claude、Cursor、Windsurf 等）
✅ 行业标准模式（STDIO 传输）
✅ 安装简单：pip install git+https://github.com/USERNAME/awx-mcp-server.git
✅ 可移植至所有兼容 MCP 的工具
✅ 18+ 项 AWX 操作（模板、作业、项目、清单）

最适合：AI 驱动的自动化、通过自然语言控制 AWX，以及任何 MCP 客户端

可选：VS Code 扩展（界面增强）

为 VS Code 用户提供的可选界面功能

适用场景：希望使用额外界面功能（侧边栏视图、树形视图提供程序）的 VS Code 用户

功能：

✅ 显示 AWX 实例、作业和指标的侧边栏
✅ AWX 资源树形视图
✅ 配置 Webview
✅ 自动配置 MCP（或遵循手动设置）

最适合：希望在使用 MCP 功能的同时获得丰富界面的 VS Code 用户

🚀 快速开始

安装方式

你可以通过 三种方式 安装并运行 AWX MCP 服务：

方式	最适合	安装
📦 PyPI (pip)	快速安装、生产环境使用	`pip install awx-mcp-server`
🔧 从源代码安装	自定义、开发、企业分支	从 GitHub 克隆并编辑代码
🐳 Docker	容器化部署、团队使用	`docker run surgexlabs/awx-mcp-server`

→ 如需自定义并从自己的仓库运行，请参阅 INSTALL_FROM_SOURCE.md

选项 1：从 PyPI 安装（快速开始推荐）

从 PyPI 安装

# Install the MCP server
pip install awx-mcp-server

# Verify installation
python -m awx_mcp_server --version

为 VS Code 配置

编辑 VS Code settings.json（Ctrl+, → 搜索“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"
      }
    }
  }
}

重启 VS Code，即可在 Copilot Chat 中使用 MCP 服务。

选项 2：从源代码安装（用于自定义）

非常适合：派生、定制、企业部署、贡献代码

快速安装：

# 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 配置（使用 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"
      }
    }
  }
}

📖 完整指南：有关以下内容，请参阅 INSTALL_FROM_SOURCE.md：

派生仓库
自定义代码
从自己的派生仓库/仓库运行
从源代码构建自定义 Docker 镜像
企业部署和 CI/CD

选项 3：远程服务模式（团队/企业）

前置条件

Python 3.10+
AWX/Ansible Tower 实例
（可选）Docker 或 Kubernetes

使用 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

使用 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 用法

# 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 用法

# 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 部署

cd server/deployment/helm

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

参阅：server/README.md 获取详细指南

🎨 集成示例

与自定义聊天机器人集成

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")

与 Slack 机器人集成

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']}")

🔧 可用的 AWX 操作

VS Code 扩展和 Web 服务均支持全部 16 项操作：

环境管理

env_list - 列出所有已配置的 AWX 环境
env_test - 测试与 AWX 环境的连接
env_get_active - 获取当前活动环境

作业模板

list_job_templates - 列出所有作业模板（支持筛选）
get_job_template - 按名称/ID 获取模板详情

作业

list_jobs - 列出所有作业（按状态、日期筛选）
get_job - 按 ID 获取作业详情
job_launch - 从模板启动作业
job_cancel - 取消正在运行的作业
job_stdout - 获取作业输出/日志
job_events - 获取作业事件（Playbook 任务）

项目

list_projects - 列出所有项目
project_update - 从 SCM 更新项目

清单

list_inventories - 列出所有清单
get_inventory - 获取清单详情

📦 项目结构

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

🏗️ 架构

VS Code 扩展架构

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

流程：

用户在 Copilot Chat 中输入 @awx list templates
扩展通过 stdio 向本地服务发送 MCP 请求
MCP 服务调用 AWX REST API
将结果返回 Copilot Chat
AI 以自然的方式组织回复

Web 服务架构

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

流程：

客户端（聊天机器人/CLI）发送包含 API 密钥的 HTTP 请求
FastAPI 服务验证请求
服务通过复合客户端调用 AWX API
以 JSON 格式返回结果
客户端为最终用户（Slack、终端等）整理结果

🔒 安全性

VS Code 扩展

凭据存储在 VS Code 安全存储中
仅运行本地服务（不暴露到网络）
基于环境的隔离

Web 服务

API 密钥身份验证（使用 SHA-256 哈希）
多租户隔离
可配置的密钥过期时间
生产环境建议使用 HTTPS
使用环境变量存储机密

🚢 部署选项

VS Code 扩展

从 .vsix 文件安装扩展
VS Code 启动时自动运行 MCP 服务
无需额外基础设施

Web 服务

开发环境

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

生产环境 - Docker

cd server
docker-compose up -d

包括：服务、Prometheus、Grafana

生产环境 - Kubernetes

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

功能：

Pod 水平自动扩缩容（HPA）
任务 Pod（每次操作创建一个临时 Job）
Prometheus 监控
支持 Ingress

🛠️ 开发

先决条件

Python 3.10+
Node.js 18+（用于 VS Code 扩展）
Docker（可选）
Kubernetes 集群（可选）

搭建开发环境

# 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

运行测试

# Server tests
cd server
pytest tests/ -v --cov

# Integration tests
cd tests
pytest test_mcp_integration.py -v

构建 VS Code 扩展

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

📊 监控（Web 服务）

访问监控仪表板：

Prometheus：http://localhost:9090
Grafana：http://localhost:3000（admin/admin）
指标端点：http://localhost:8000/prometheus-metrics

可用指标

awx_mcp_requests_total - 按租户/端点统计的请求总数
awx_mcp_request_duration_seconds - 请求延迟
awx_mcp_active_connections - 每个租户的活动连接数
awx_mcp_tool_calls_total - MCP 工具调用次数
awx_mcp_errors_total - 按类型统计的错误数

📚 文档

安装与设置

从 PyPI 安装 - 使用 pip install awx-mcp-server 快速安装
从源代码安装 - Fork、定制，并从自己的仓库运行
操作系统兼容性 - Windows、macOS 和 Linux 的安装与配置

平台支持

AAP 支持指南 - Ansible Automation Platform、AWX 和 Ansible Tower 完整指南

部署架构

部署架构 - 单用户与团队/企业部署选项
远程部署指南 - Docker、Kubernetes 和云端部署
双模式快速入门 - 选择部署模式的快速参考

高级功能（计划中）

Vault 集成 - 支持 HashiCorp Vault、AWS Secrets Manager、Azure Key Vault（v2.0.0）
实现状态 - 当前功能和路线图

其他资源

MCP Copilot 设置 - VS Code MCP 配置
快速参考 - 常用命令和示例
AWX MCP 查询参考 - 自然语言查询示例

🤝 参与贡献

欢迎贡献！请：

Fork 此仓库
创建功能分支
编写代码并添加测试
提交拉取请求

代码风格

Python：遵循 PEP 8，使用类型提示
TypeScript：遵循 ESLint 规则
为新功能编写测试
更新文档

📄 许可证

MIT 许可证 - 详见 LICENSE 文件

🆘 支持

问题：https://github.com/your-org/awx-mcp/issues
讨论：https://github.com/your-org/awx-mcp/discussions
文档：参阅子目录中的 README 文件

🎉 快速参考

VS Code 扩展命令

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

Web 服务 CLI 命令

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 服务 API 端点

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

为 AWX 自动化和 AI 集成倾情打造 ❤️

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

awx-mcp-server

关于 awx-mcp-server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

AWX MCP - AI 驱动的 AWX/AAP/Ansible 自动化

🎯 使用模式

主要方式：MCP 服务（行业标准）⭐ 推荐

可选：VS Code 扩展（界面增强）

🚀 快速开始

安装方式

选项 1：从 PyPI 安装（快速开始推荐）

从 PyPI 安装

为 VS Code 配置

选项 2：从源代码安装（用于自定义）

选项 3：远程服务模式（团队/企业）

前置条件

使用 Docker 快速开始

使用 Python 快速开始

CLI 用法

REST API 用法

Kubernetes 部署

🎨 集成示例

与自定义聊天机器人集成

与 Slack 机器人集成

🔧 可用的 AWX 操作

环境管理

作业模板

作业

项目

清单

📦 项目结构

🏗️ 架构

VS Code 扩展架构

Web 服务架构

🔒 安全性

VS Code 扩展

Web 服务

🚢 部署选项

VS Code 扩展

Web 服务

开发环境

生产环境 - Docker

生产环境 - Kubernetes

🛠️ 开发

先决条件

搭建开发环境

运行测试

构建 VS Code 扩展

📊 监控（Web 服务）

可用指标

📚 文档

安装与设置

平台支持

部署架构

高级功能（计划中）

其他资源

🤝 参与贡献

代码风格

📄 许可证

🆘 支持

🎉 快速参考

VS Code 扩展命令

Web 服务 CLI 命令

Web 服务 API 端点

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？