使用说明

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作业的状态和详细信息。

参数	类型	必填	说明
`job_id`	integer	是	AWX作业ID

`awx_stream_job_logs`

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

参数	类型	必填	说明
`job_id`	integer	是	AWX作业ID
`follow`	boolean	no	轮询直到作业完成（默认值：false）

`awx_list_inventories`

列出可用的AWX库存。

参数	类型	必填	说明
`page`	integer	no	页码（默认值：1）
`page_size`	integer	否	每页结果数（默认值：50）

`awx_get_inventory_hosts`

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

参数	类型	必填	说明
`inventory_id`	integer	其中之一	库存ID
`inventory_name`	string	其中之一	库存名称

`awx_get_host_variables`

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

参数	类型	必填	说明
`host_id`	integer	其中之一	主机ID
`host_name`	string	其中之一	主机FQDN

`awx_search_job_templates`

搜索AWX作业模板。

参数	类型	必填	说明
`name_filter`	string	no	模板名称上的子字符串匹配
`limit`	integer	no	最大结果（默认值：50）

`awx_list_recent_jobs`

列出最近执行的AWX作业。

参数	类型	必填	说明
`status`	string	no	筛选器：成功、失败、正在运行、挂起、取消、错误
`limit`	integer	no	最大结果（默认值：20）

配置

变量	描述	必填
`AWX_URL`	AWX基本URL（例如。， `https://awx.example.com`)	是的
`AWX_USERNAME`	AWX用户名	是
`AWX_PASSWORD`	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获取实时数据

发展

添加新工具

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

依赖项

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

安装

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在每个版本上发布。

发布

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

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

使用说明

AWX MCP服务器

建筑

特性

快速开始

先决条件

使用已发布的图像

从源代码构建

配置Claude代码

验证

可用工具

awx_get_job_status

awx_stream_job_logs

awx_list_inventories

awx_get_inventory_hosts

awx_get_host_variables

awx_search_job_templates

awx_list_recent_jobs

配置

测试

手动stdio测试

交互式测试

故障排除

在Claude代码中找不到工具

认证失败

无法连接到AWX

安全

局限性

发展

添加新工具

依赖项

相关

安装

Docker镜像

发布

相关 MCP

Figma MCP服务器

Markdown转换服务

MCP 协议测试服务器

图像生成服务

代码安全扫描工具

网页内容抓取服务器