convez.ai
MCP ServerDevOps & InfraestruturaAvançado
lycorp-jp

AWX MCP Server

lycorp-jp/awx-mcp

Integre AWX com IA via 146 ferramentas MCP para automação de infraestrutura

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP que conecta assistentes de IA (como Claude) à plataforma AWX via REST API v2. Oferece 146 ferramentas para gerenciar inventários, hosts, templates de jobs, workflows, credenciais e configurações de infraestrutura de forma conversacional.

Instalação

$npx convez-ai lycorp-jp/awx-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
9
Forks
5
Acompanhando
0
Saúde
87%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Automação de deployments e orquestração via linguagem natural
  • Gerenciamento remoto de inventários e hosts no AWX
  • Consultas e operações de RBAC e credenciais com segurança

Veredito

Solução robusta e completa para DevOps que democratiza o acesso ao AWX via linguagem natural. Requer setup técnico e conhecimento de AWX, mas reduz significativamente fricção em operações repetitivas de infraestrutura.

README

A tradução para o português deste README ainda está na fila.

AWX MCP Server

Python License MCP Tools AWX

An MCP (Model Context Protocol) server that lets LLMs interact with AWX instances.

🇰🇷 한국어 | 🇯🇵 日本語

146 tools covering every major AWX capability: inventories, hosts, projects, job templates, workflows, credentials, execution environments, RBAC, and system administration.

142 tools are enabled by default. The remaining 4 (create_credential, update_credential, create_user, update_user) collect sensitive data via Form-mode elicitation and are gated behind AWX_MCP_ENABLE_CREDENTIAL_MANAGEMENT=true. See Credential Management.


Table of Contents


Quick Start

This server runs from a local clone with uv. Clone the repo and sync dependencies once:

git clone https://github.com/lycorp-jp/awx-mcp
cd awx-mcp
uv sync          # creates .venv and installs dependencies

Then point your MCP client at the clone using uv run --directory <path>. Replace /path/to/awx-mcp with the absolute path to your clone.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "awx": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/awx-mcp", "awx-mcp"],
      "env": {
        "ANSIBLE_BASE_URL": "https://awx.example.com/",
        "ANSIBLE_TOKEN": "your_api_token",
        "ANSIBLE_SSL_VERIFY": "false"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add awx \
  -e ANSIBLE_BASE_URL=https://awx.example.com/ \
  -e ANSIBLE_TOKEN=your_api_token \
  -e ANSIBLE_SSL_VERIFY=false \
  -- uv run --directory /path/to/awx-mcp awx-mcp

Once configured, ask the LLM in plain language: "Show me the list of inventories registered in AWX."


Prerequisites

  • A reachable AWX instance and its base URL (REST API v2), plus an API token (or username + password) with appropriate permissions
  • uv

Architecture

flowchart LR
    User([User])
    LLM[LLM<br/>Claude / GPT / etc.]
    MCP[MCP Client<br/>Claude Desktop<br/>Claude Code<br/>Cline / etc.]
    AWX_MCP["AWX MCP Server<br/>(awx-mcp)<br/>146 tools (142 default + 4 opt-in)"]
    AWX[AWX<br/>REST API v2]

    User -- natural language request --> LLM
    LLM -- tool selection & invocation --> MCP
    MCP -- "STDIO / SSE / HTTP" --> AWX_MCP
    AWX_MCP -- HTTPS --> AWX

    style AWX_MCP fill:#1a73e8,color:#fff
    style AWX fill:#ee0000,color:#fff

The LLM analyzes the user's request, selects the appropriate MCP tool, and the AWX MCP server calls the AWX REST API and returns the result.

This server supports STDIO (default), SSE, and Streamable HTTP transports. Use STDIO for local MCP clients; use SSE or Streamable HTTP for remote or shared deployments.


Compatibility

ComponentSupported
AWX24.6.1 (REST API v2)
Python≥ 3.10
MCP transportSTDIO, SSE, Streamable HTTP

Features

AWX Resource Management

Full management across inventories, hosts, groups, job templates, jobs, projects, workflows, credentials, RBAC, organizations/teams/users, execution environments, schedules, and system administration. See Tools for the full list.

Technical Highlights

  • Modular directory structure: 20 domain modules for clean separation of concerns and easier maintenance
  • Token caching: reuses OAuth2 tokens when authenticating with username/password to avoid unnecessary token creation
  • Pagination control: caps each response at the requested number of records via the limit parameter, so large result sets never flood the LLM context
  • Safe by default: 4 credential/user write tools that collect sensitive data are not registered unless AWX_MCP_ENABLE_CREDENTIAL_MANAGEMENT=true is set. The default deployment exposes no tool that handles sensitive data — see Credential Management
  • Reduced parameter exposure (when opt-in is enabled): credential inputs and passwords are collected via MCP Elicitation (Form mode) instead of being passed as tool parameters
  • Read-only mode: set AWX_MCP_READ_ONLY=true to expose only read tools (list_*/get_*) at startup

Installation

This server is not published to any package index — run it from a local clone with uv.

# 1. Clone the repository
git clone https://github.com/lycorp-jp/awx-mcp
cd awx-mcp

# 2. Sync dependencies (creates .venv automatically)
uv sync

# 3. Set required environment variables
export ANSIBLE_BASE_URL="https://awx.example.com/"
export ANSIBLE_TOKEN="your_api_token"
export ANSIBLE_SSL_VERIFY="false"

# 4a. Run with stdio (default — for local MCP clients)
uv run awx-mcp

# 4b. Run with Streamable HTTP (for remote/shared access)
uv run awx-mcp --transport streamable-http --host 127.0.0.1 --port 8000
#    Endpoint: http://127.0.0.1:8000/mcp

# 4c. Run with SSE
uv run awx-mcp --transport sse --port 8000
#    Endpoint: http://127.0.0.1:8000/sse

When configuring an MCP client, run from any directory by passing the clone path with --directory:

uv run --directory /path/to/awx-mcp awx-mcp

CLI flags (--transport, --host, --port) override the AWX_MCP_TRANSPORT, AWX_MCP_HOST, and AWX_MCP_PORT environment variables.

For stdio, you normally let the MCP client launch the process automatically (see MCP Client Integration) rather than running it by hand.


Configuration

Set AWX connection details via environment variables. Put them directly in the env block of your MCP client config.

Required

VariableDescriptionExample
ANSIBLE_BASE_URLAWX instance URL (trailing / optional)https://awx.example.com

Authentication (choose one)

Option 1: API token (recommended)

Use a token generated in advance from the AWX UI. Tokens don't expire, so this is the more stable option.

VariableDescription
ANSIBLE_TOKENPre-generated API token

To generate a token in AWX: User Profile > Tokens > Add > Scope: Write

Option 2: Username + password

The server automatically creates and caches an OAuth2 token on your behalf.

VariableDescription
ANSIBLE_USERNAMEAWX username
ANSIBLE_PASSWORDAWX password

Optional

VariableDefaultDescription
ANSIBLE_SSL_VERIFYfalseSSL certificate verification (true/false)
ANSIBLE_LOG_LEVELINFOLog level (DEBUG, INFO, WARNING, ERROR)
AWX_MCP_ENABLE_CREDENTIAL_MANAGEMENTfalseOpt-in for the 4 credential/user write tools that collect sensitive data via Form-mode elicitation. See Credential Management.
AWX_MCP_READ_ONLYfalseWhen true, all write/destructive tools are unregistered at startup; only read-only tools (list_*/get_*) are exposed. Useful for safe inspection or audit-only automation.
AWX_MCP_TRANSPORTstdioMCP transport to use: stdio, sse, or streamable-http.
AWX_MCP_HOST127.0.0.1Bind host for sse and streamable-http transports.
AWX_MCP_PORT8000Bind port for sse and streamable-http transports.

Credential Management (opt-in)

Four tools — create_credential, update_credential, create_user, update_user — collect sensitive data (passwords, credential inputs) via Form-mode elicitation. They are not registered by default, so the default 142-tool surface exposes nothing that handles sensitive data.

To enable them, set:

AWX_MCP_ENABLE_CREDENTIAL_MANAGEMENT=true

Form-mode elicitation is not spec-compliant for sensitive data per the MCP specification — the response may still be exposed through client-side logging or other intermediate systems. Enable only in trusted, isolated environments. For the full threat model and disclosure policy, see SECURITY.md.


MCP Client Integration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "awx": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/awx-mcp", "awx-mcp"],
      "env": {
        "ANSIBLE_BASE_URL": "https://awx.example.com/",
        "ANSIBLE_TOKEN": "your_api_token",
        "ANSIBLE_SSL_VERIFY": "false"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add awx \
  -e ANSIBLE_BASE_URL=https://awx.example.com/ \
  -e ANSIBLE_TOKEN=your_api_token \
  -e ANSIBLE_SSL_VERIFY=false \
  -- uv run --directory /path/to/awx-mcp awx-mcp

Cline (VS Code)

Add to the MCP server config:

{
  "awx": {
    "command": "uv",
    "args": ["run", "--directory", "/path/to/awx-mcp", "awx-mcp"],
    "env": {
      "ANSIBLE_BASE_URL": "https://awx.example.com/",
      "ANSIBLE_TOKEN": "your_api_token",
      "ANSIBLE_SSL_VERIFY": "false"
    }
  }
}

HTTP & SSE transports

When the server is running with --transport streamable-http or --transport sse, point your MCP client at the HTTP endpoint instead of using a subprocess command.

Streamable HTTP (endpoint: http://host:8000/mcp):

{
  "mcpServers": {
    "awx": { "type": "streamable-http", "url": "http://127.0.0.1:8000/mcp" }
  }
}

SSE (endpoint: http://host:8000/sse):

{
  "mcpServers": {
    "awx": { "type": "sse", "url": "http://127.0.0.1:8000/sse" }
  }
}

Security (IMPORTANT): The HTTP/SSE transports have no built-in authentication. By default the server binds to 127.0.0.1 (loopback only). If you bind to a non-loopback address the server logs a warning. For any network-exposed deployment, place the server behind an authenticating TLS reverse proxy and restrict port access with a firewall. Never expose the server directly to untrusted networks.


Usage Examples

Send natural language requests to your MCP client (Claude, etc.) and the server calls the appropriate tools.

Inventory management

"Show me the hosts in the Production inventory"
-> list_hosts(inventory_id=1)

"Add web-server-01 to the Production inventory"
-> create_host(name="web-server-01", inventory_id=1)

"Group the DB servers into a database group"
-> create_group(...) + add_host_to_group(...)

Job execution and monitoring

"Run the Deploy App job template"
-> launch_job(template_id=5)

"Check the status of the job I just ran"
-> get_job(job_id=123)

"Show me the job execution log"
-> get_job_stdout(job_id=123)

"Rerun the failed job"
-> relaunch_job(job_id=123)

Projects and SCM

"Sync all projects to the latest version"
-> list_projects() + sync_project(project_id=...) for each

"List the playbooks in my-project"
-> list_project_playbooks(project_id=3)

Workflows

"Run the deployment workflow and approve it if approval is needed"
-> launch_workflow(template_id=10)
-> list_workflow_approvals() -> approve_workflow(approval_id=...)

"Check which nodes failed in the workflow run"
-> list_workflow_job_nodes(workflow_job_id=50)

RBAC and user management

"Grant the developer team read access to the Production inventory"
-> list_object_roles(...) + grant_role_to_team(role_id=..., team_id=...)

"Create a new user john and add them to the DevOps team"
-> create_user(...) + grant_role_to_user(...)

System administration

"Check the AWX version and cluster status"
-> get_ansible_version() + list_instances()

"Clean up job records older than 90 days"
-> list_system_job_templates() -> launch_system_job(template_id=..., extra_vars='{"days": 90}')

Tools

146 tools across 20 modules. By default 142 are registered; the 4 marked opt-in below appear only when AWX_MCP_ENABLE_CREDENTIAL_MANAGEMENT=true (see Credential Management).

Inventories & Inventory Sources (14) - inventories.py

ToolDescription
list_inventoriesList all inventories
get_inventoryGet details of a specific inventory
create_inventoryCreate a new inventory
update_inventoryUpdate an inventory
delete_inventoryDelete an inventory
list_inventory_sourcesList inventory sources
get_inventory_sourceGet details of a specific inventory source
create_inventory_sourceCreate a new inventory source
update_inventory_sourceUpdate an inventory source
sync_inventory_sourceSync an inventory source
delete_inventory_sourceDelete an inventory source
list_inventory_updatesList inventory update (sync) history
get_inventory_updateGet details of a specific inventory update
cancel_inventory_updateCancel a running inventory update

Host Management (5) - hosts.py

ToolDescription
list_hostsList hosts (filterable by inventory)
get_hostGet details of a specific host
create_hostCreate a new host (with variables)
update_hostUpdate a host
delete_hostDelete a host

Group Management (7) - groups.py

ToolDescription
list_groupsList groups within an inventory
get_groupGet details of a specific group
create_groupCreate a new group (with variables)
update_groupUpdate a group
delete_groupDelete a group
add_host_to_groupAdd a host to a group
remove_host_from_groupRemove a host from a group

Job Template Management (13) - job_templates.py

ToolDescription
list_job_templatesList all job templates
get_job_templateGet details of a specific job template
create_job_templateCreate a new job template
update_job_templateUpdate a job template
delete_job_templateDelete a job template
launch_jobLaunch a job from a job template
copy_job_templateCopy a job template
get_job_template_surveyGet the survey for a job template
set_job_template_surveySet the survey for a job template
delete_job_template_surveyDelete the survey from a job template
list_template_credentialsList credentials associated with a template
associate_credential_with_templateAssociate a credential with a template
disassociate_credential_from_templateRemove a credential from a template

Job Management (7) - jobs.py

ToolDescription
list_jobsList jobs (filterable by status)
get_jobGet details of a specific job
cancel_jobCancel a running job
relaunch_jobRelaunch a completed or failed job
get_job_eventsList job events
get_job_stdoutGet job stdout (txt/html/json/ansi)
get_job_host_summariesGet per-host job result summaries

Project Management (11) - projects.py

ToolDescription
list_projectsList all projects
get_projectGet details of a specific project
create_projectCreate a new project (Git/SVN/Hg/manual)
update_projectUpdate a project
delete_projectDelete a project
sync_projectSync a project with its SCM source
list_project_playbooksList playbooks in a project
list_project_updatesList project update (sync) history
get_project_updateGet details of a specific project update
cancel_project_updateCancel a running project update
get_project_update_stdoutGet stdout from a project update

Credential Management (7: 5 default + 2 opt-in) - credentials.py

ToolDescription
list_credentialsList all credentials
get_credentialGet details of a specific credential
list_credential_typesList credential types
create_credentialopt-in. Create a new credential (collects sensitive inputs via elicitation)
update_credentialopt-in. Update a credential (may collect sensitive inputs via elicitation)
delete_credentialDelete a credential
copy_credentialCopy a credential

Organization Management (5) - organizations.py

ToolDescription
list_organizationsList all organizations
get_organizationGet details of a specific organization
create_organizationCreate a new organization
update_organizationUpdate an organization
delete_organizationDelete an organization

Team Management (5) - teams.py

ToolDescription
list_teamsList teams (filterable by organization)
get_teamGet details of a specific team
create_teamCreate a new team
update_teamUpdate a team
delete_teamDelete a team

User Management (5: 3 default + 2 opt-in) - users.py

ToolDescription
list_usersList all users
get_userGet details of a specific user
create_useropt-in. Create a new user (collects password via elicitation)
update_useropt-in. Update a user (may collect password via elicitation)
delete_userDelete a user

Ad Hoc Commands (3) - ad_hoc.py

ToolDescription
run_ad_hoc_commandRun an ad hoc Ansible command
get_ad_hoc_commandGet details of an ad hoc command
cancel_ad_hoc_commandCancel a running ad hoc command

Workflow Templates & Nodes (17) - workflow_templates.py

ToolDescription
list_workflow_templatesList all workflow templates
get_workflow_templateGet details of a specific workflow template
create_workflow_templateCreate a new workflow template
update_workflow_templateUpdate a workflow template
delete_workflow_templateDelete a workflow template
launch_workflowLaunch a workflow
copy_workflow_templateCopy a workflow template
get_workflow_template_surveyGet the survey for a workflow template
set_workflow_template_surveySet the survey for a workflow template
delete_workflow_template_surveyDelete the survey from a workflow template
list_workflow_template_nodesList nodes in a workflow template
get_workflow_template_nodeGet details of a specific node
create_workflow_template_nodeCreate a new node
delete_workflow_template_nodeDelete a node
add_workflow_node_success_linkLink a node to run on success
add_workflow_node_failure_linkLink a node to run on failure
add_workflow_node_always_linkLink a node to always run

Workflow Jobs & Approvals (11) - workflow_jobs.py

ToolDescription
list_workflow_jobsList workflow jobs (filterable by status)
get_workflow_jobGet details of a specific workflow job
cancel_workflow_jobCancel a running workflow job
relaunch_workflow_jobRelaunch a completed or failed workflow job
list_workflow_job_nodesList nodes from a workflow run (for debugging)
list_workflow_approvalsList pending workflow approval requests
get_workflow_approvalGet details of a specific approval request
approve_workflowApprove a workflow
deny_workflowDeny a workflow
list_workflow_approval_templatesList workflow approval templates
get_workflow_approval_templateGet details of a specific approval template

Schedule Management (5) - schedules.py

ToolDescription
list_schedulesList schedules (filterable by template)
get_scheduleGet details of a specific schedule
create_scheduleCreate a new schedule (iCal rrule)
update_scheduleUpdate a schedule
delete_scheduleDelete a schedule

Execution Environments (5) - execution_environments.py

ToolDescription
list_execution_environmentsList execution environments
get_execution_environmentGet details of a specific execution environment
create_execution_environmentCreate a new execution environment
update_execution_environmentUpdate an execution environment
delete_execution_environmentDelete an execution environment

Notification Templates (3) - notifications.py

ToolDescription
list_notification_templatesList notification templates
get_notification_templateGet details of a specific notification template
test_notification_templateSend a test notification

Label Management (2) - labels.py

ToolDescription
list_labelsList labels
create_labelCreate a new label

RBAC Role Management (7) - rbac.py

ToolDescription
list_rolesList RBAC roles
get_roleGet details of a specific role
grant_role_to_userGrant a role to a user
revoke_role_from_userRevoke a role from a user
grant_role_to_teamGrant a role to a team
revoke_role_from_teamRevoke a role from a team
list_object_rolesList RBAC roles for a specific resource

Instance Management (4) - instances.py

ToolDescription
list_instancesList cluster instances
get_instanceGet details of a specific instance
list_instance_groupsList instance groups
get_instance_groupGet details of a specific instance group

System Administration (10) - system.py

ToolDescription
list_activity_streamQuery audit log (filterable by object type/ID)
get_configGet AWX configuration
get_ansible_versionGet AWX version information
get_dashboard_statsGet dashboard statistics
get_metricsGet system metrics
list_system_job_templatesList system job templates (cleanup, analytics, etc.)
get_system_job_templateGet details of a specific system job template
launch_system_jobLaunch a system maintenance job
list_system_jobsList system job execution history
get_system_jobGet details of a specific system job

Troubleshooting

Server won't start

ValueError: ANSIBLE_BASE_URL environment variable is required

The environment variable isn't set. Add ANSIBLE_BASE_URL to the env block in your MCP client config.

ValueError: Authentication is required

You need to set either ANSIBLE_TOKEN or both ANSIBLE_USERNAME and ANSIBLE_PASSWORD.

Connection problems

SSL certificate error

If you're using a self-signed certificate, set ANSIBLE_SSL_VERIFY to "false" (the string, not a boolean).

Connection refused / timeout

  • Verify ANSIBLE_BASE_URL is correct
  • Confirm the AWX instance is running
  • Check firewall and network settings

MCP schema error

Does not adhere to MCP server configuration schema

All values in the env block must be strings. Use "false" instead of false.

Permission errors

403 Forbidden

The API token or user account doesn't have permission for that resource. Ask your AWX administrator to assign the appropriate role.

Debugging

Set the log level to DEBUG to see detailed API request and response logs:

"ANSIBLE_LOG_LEVEL": "DEBUG"

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on how to submit issues, propose changes, and open pull requests.

Code of Conduct

This project follows the Code of Conduct. By participating you agree to abide by its terms.

Changelog

See CHANGELOG.md for a history of notable changes.

Security Policy

For vulnerability disclosure, the threat model, and security history, see SECURITY.md.


License

Apache License 2.0. See LICENSE for details.

Ver o original no GitHub

Bom para

Relacionados