awx MCP

AWX MCP服务器

模型上下文协议（MCP）服务器，提供用于与AWX API交互的结构化工具。这使Claude Code能够查询作业状态、流式日志、检查库存和搜索模板，而无需构造手动curl命令。

建筑

┌─────────────────────────────────────────────────────────────┐
│ Claude Code (Main Agent)                                     │
│   │                                                          │
│   ├──calls──> mcp__awx__get_job_status                      │
│   ├──calls──> mcp__awx__stream_job_logs                     │
│   ├──calls──> mcp__awx__list_inventories                    │
│   └──calls──> mcp__awx__search_job_templates                │
│                                                              │
│   via stdio (stdin/stdout)                                   │
└───────────────────┬──────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│ AWX MCP Server (Docker Container)                           │
│   - Reads JSON-RPC requests from stdin                      │
│   - Writes JSON-RPC responses to stdout                     │
│   - Wraps AWX API with authentication                       │
└───────────────────┬──────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────┐
│ AWX API (/api/v2/)                                          │
└─────────────────────────────────────────────────────────────┘

这是一个 本地开发工具 它通过stdio传输在Docker中运行。

特性

• 作业状态查询：检查AWX作业的状态、运行时和详细信息
• 日志流：查看作业执行输出（可选实时轮询）
• 库存管理：列出库存、查看主机、检查主机变量
• 模板搜索：查找可用的作业模板和作业手册
• 工作经历：使用筛选查看最近执行的作业

快速开始

先决条件

• Docker已安装并正在运行
• AWX凭据（URL、用户名、密码）

使用已发布的图像

从GitHub容器注册表中提取最新版本：

docker pull ghcr.io/listellm/awx-mcp:latest

或者使用特定版本：

docker pull ghcr.io/listellm/awx-mcp:v1.0.1

从源代码构建

或者，在本地构建：

docker build -t awx-mcp-server:latest .

配置Claude代码

增添 .vscode/mcp.json 在您的项目中：

{
  "servers": {
    "awx": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "AWX_URL",
        "-e", "AWX_USERNAME",
        "-e", "AWX_PASSWORD",
        "ghcr.io/listellm/awx-mcp:latest"
      ]
    }
  }
}

备注：替换 ghcr.io/listellm/awx-mcp:latest 随着 awx-mcp-server:latest 如果你从源代码构建。

在启动Claude Code之前，在shell中设置环境变量，或使用 --env-file:

{
  "servers": {
    "awx": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env-file", "/path/to/.env",
        "ghcr.io/listellm/awx-mcp:latest"
      ]
    }
  }
}

验证

重新启动Claude Code后，使用 ToolSearch(query="awx") 确认所有7个工具都可用。

可用工具

所有工具都是 只读 （仅GET请求）。前缀为 mcp__awx__ 克劳德密码。

awx_get_job_status

获取AWX作业的状态和详细信息。

awx_stream_job_logs

检索作业执行日志，并对正在运行的作业进行可选轮询。

awx_list_inventories

列出可用的AWX库存。

awx_get_inventory_hosts

在清单中获取所有主机。提供其中之一 inventory_id 或 inventory_name.

awx_get_host_variables

获取特定主机的变量。提供其中之一 host_id 或 host_name.

awx_search_job_templates

搜索AWX作业模板。

awx_list_recent_jobs

列出最近执行的AWX作业。

配置

测试

手动stdio测试

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  | docker run -i --rm \
    -e AWX_URL=https://awx.example.com \
    -e AWX_USERNAME=test \
    -e AWX_PASSWORD=test \
    ghcr.io/listellm/awx-mcp:latest

预期响应：

{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "0.1.0", "serverInfo": {"name": "awx-mcp-server", "version": "0.1.0"}, "capabilities": {"tools": {}}}}

交互式测试

docker run -i --rm --env-file .env ghcr.io/listellm/awx-mcp:latest

然后逐行发送JSON-RPC请求：

{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "awx_list_recent_jobs", "arguments": {"limit": 5}}}

按 Ctrl+D 退出。

故障排除

在Claude代码中找不到工具

• 验证 .vscode/mcp.json 存在并且是有效的JSON
• 检查图像是否已构建： docker images awx-mcp-server
• 完全重新启动Claude代码（而不仅仅是重新加载）
• 使用 ToolSearch(query="awx") 验证

认证失败

• 验证环境变量是否包含正确的凭据
• 手动测试： curl -u "user:pass" https://awx.example.com/api/v2/ping/

无法连接到AWX

• 检查与AWX实例的网络连接
• 验证Docker容器是否可以访问AWX（可能需要主机联网 --network host)

安全

• 只读：所有工具仅执行GET请求
• 无端口：仅限stdio（无EXPOSE，无监听套接字）
• 通过env获取凭据：未烘焙成图像
• 无状态：无持久存储

局限性

• 没有作业启动：无法触发AWX作业（按设计）
• 基于轮询的流媒体：每2秒记录一次流式轮询（AWX不支持WebSocket）
• 单个实例：为每个容器配置一个AWX实例
• 无缓存：始终从AWX API获取实时数据

发展

添加新工具

1. 将AWX API方法添加到 src/awx_client.py
2. 注册工具 @mcp.tool() 室内装饰师 src/awx_mcp_server.py
3. 执行工具处理程序功能
4. 重建Docker镜像

依赖项

• 主控程序：官方模型上下文协议Python SDK
• 请求：：AWX API调用的HTTP客户端
• 仅在其他情况下使用标准库（最大限度地减少攻击面）

相关

• 模型上下文协议
• AWX项目
• 克劳德代码

安装

Docker镜像

已发布的版本可在GitHub容器注册表上找到：

docker pull ghcr.io/listellm/awx-mcp:latest    # Latest stable
docker pull ghcr.io/listellm/awx-mcp:v1        # Latest v1.x
docker pull ghcr.io/listellm/awx-mcp:v1.0      # Latest v1.0.x
docker pull ghcr.io/listellm/awx-mcp:v1.0.1    # Specific version

图像会自动构建并通过GitHub Actions在每个版本上发布。

发布

看 查看完整的更新日志和发行说明。

• v1.0.x：生产准备就绪，自动发布
• v0.1.0：初步实施