rfxsx/awx-mcp-tool repository overview

⁠awx-mcp-tool

Model Context Protocol (MCP) server for Ansible AWX (open-source). Connect AI coding assistants (Cursor, Cline, Windsurf, and others) to your AWX instance: discover inventories and job templates, monitor runs, handle workflow approvals, and launch jobs — all via MCP tools over SSE.

⁠Features

• 17 MCP tools for AWX REST API v2 (discovery, monitoring, approvals, launch)
• SSE transport on port 8000 (default) — same transport Cursor uses
• Per-client Bearer token via Authorization header (shared Docker instance, individual AWX users)
• Stateless — no database; AWX is the system of record
• Python 3.12, FastMCP, async httpx, pydantic v2

⁠Authentication model (SSE)

The container does not need your personal API token for normal SSE use. Each developer puts their own token in the MCP client config; the server reads it from the HTTP header on every tool call.

Optional: set AWX_TOKEN in the container env only for startup health probe, stdio transport, or legacy fallback — not required when the client sends Authorization.

⁠Quick start

1. Run the server (only AWX_URL on the container):

docker pull YOUR_USER/awx-mcp-tool:latest

docker run -d --name awx-mcp-tool \
  -p 8000:8000 \
  -e AWX_URL=https://awx.example.com \
  -e MCP_TRANSPORT=sse \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  rfxsx/awx-mcp-tool:latest

2. Configure your MCP client (token here, not in Docker):

{
  "mcpServers": {
    "awx-mcp-tool": {
      "url": "http://127.0.0.1:8000/sse",
      "headers": {
        "Authorization": "Bearer YOUR_AWX_API_TOKEN"
      }
    }
  }
}

⁠MCP tools (summary)

Put your API token in .cursor/mcp.json (or equivalent) under headers.Authorization, not in Compose unless you want the optional server-side fallback.

⁠Requirements

• AWX open-source with API token (Bearer)
• Outbound HTTPS/HTTP from the container to AWX_URL
• MCP client with SSE support