awx-mcp-server — MCP server for AWX: launch jobs, read output
Wires AWX, AAP or Ansible Tower into an AI agent so job templates, inventories and projects get handled in chat. Handy when your Ansible automation already lives in AWX.
claude mcp add --env AWX_BASE_URL=<AWX_BASE_URL> --env AWX_TOKEN=<AWX_TOKEN> --env AWX_USERNAME=<AWX_USERNAME> --env AWX_PASSWORD=<AWX_PASSWORD> --env AWX_VERIFY_SSL=<AWX_VERIFY_SSL> --transport stdio awx-mcp-server -- uvx awx-mcp-serverWhat awx-mcp-server does
The server speaks STDIO and exposes AWX operations to the model: job templates, launching and watching jobs, projects, inventories. Your agent can kick off a deploy or pull the output of a failed run without leaving the editor.
It ships as a Python package and starts with uvx awx-mcp-server. The repo also carries a CLI (awx-mcp-server jobs launch, awx-mcp-server templates list), a REST API and Docker or Helm deployment for teams. Keep in mind those are documented paths; talking to an agent only needs the STDIO part.
You must supply the instance URL and credentials before anything connects: AWX_BASE_URL plus either AWX_TOKEN or AWX_USERNAME with AWX_PASSWORD. Set AWX_VERIFY_SSL if your certificate is self-signed. The setup walkthrough leans on VS Code and Copilot Chat, so for other clients you assemble the config from the same environment variables. No reachable AWX API, no tools.
What it helps with
- run a job template and watch it finish from the editor
- read stdout of a failed job without opening the AWX UI
- list inventories and projects before a deploy
- give an agent token-scoped access to Ansible automation
- grab job output for an incident write-up
Example prompts for the agent
- List every job template in AWX and flag the ones that failed last time.
- Launch the Deploy App template with extra vars
{"env":"prod"}and report back. - Fetch stdout for job 123 and point out the error.
How to install awx-mcp-server
Platform CLI
claude mcp add --env AWX_BASE_URL=<AWX_BASE_URL> --env AWX_TOKEN=<AWX_TOKEN> --env AWX_USERNAME=<AWX_USERNAME> --env AWX_PASSWORD=<AWX_PASSWORD> --env AWX_VERIFY_SSL=<AWX_VERIFY_SSL> --transport stdio awx-mcp-server -- uvx awx-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from awx-mcp-server <command>
Platform CLI
codex mcp add awx-mcp-server --env AWX_BASE_URL=<AWX_BASE_URL> --env AWX_TOKEN=<AWX_TOKEN> --env AWX_USERNAME=<AWX_USERNAME> --env AWX_PASSWORD=<AWX_PASSWORD> --env AWX_VERIFY_SSL=<AWX_VERIFY_SSL> -- uvx awx-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from awx-mcp-server <command>
Config file
{
"mcpServers": {
"awx-mcp-server": {
"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>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from awx-mcp-server <command>
Config file
{
"servers": {
"awx-mcp-server": {
"type": "stdio",
"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>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from awx-mcp-server <command>
Platform CLI
gemini mcp add -e AWX_BASE_URL=<AWX_BASE_URL> -e AWX_TOKEN=<AWX_TOKEN> -e AWX_USERNAME=<AWX_USERNAME> -e AWX_PASSWORD=<AWX_PASSWORD> -e AWX_VERIFY_SSL=<AWX_VERIFY_SSL> awx-mcp-server uvx awx-mcp-serverReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from awx-mcp-server <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about awx-mcp-server
How do I install awx-mcp-server in Claude Code?
Run claude mcp add awx-mcp-server -e AWX_BASE_URL=<AWX_BASE_URL> -e AWX_TOKEN=<AWX_TOKEN> -e AWX_PASSWORD=<AWX_PASSWORD> -- uvx awx-mcp-server. The fuller form: `claude mcp add --env AWX_BASE_URL=<AWX_BASE_URL> --env AWX_TOKEN=<AWX_TOKEN> --env AWX_USERNAME=<AWX_USERNAME> --env AWX_PASSWORD=<AWX_PASSWORD> --env AWX_VERIFY_SSL=<AWX_VERIFY_SSL> --transport stdio awx-mcp-server -- uvx awx-mcp-server`.
What does awx-mcp-server do?
It hands the agent tools for AWX, AAP and Ansible Tower — job templates, job launch and monitoring, projects, inventories. You describe the task in plain text instead of clicking through the dashboard.
What do I need before connecting it?
The instance URL in AWX_BASE_URL and working credentials: AWX_TOKEN, or a username and password pair. Add AWX_VERIFY_SSL when the certificate is self-signed.
