Version: 1.3.54

The Ansible Tower MCP Server provides a Model Context Protocol (MCP) interface to interact with the Ansible Tower (AWX) API, enabling automation and management of Ansible Tower resources such as inventories, hosts, groups, job templates, projects, credentials, organizations, teams, users, ad hoc commands, workflow templates, workflow jobs, schedules, and system information. This server is designed to integrate seamlessly with AI-driven workflows and can be deployed as a standalone service or used programmatically.

This repository is actively maintained - This is a fork of a37ai/ansible-tower-mcp, which had not been updated in 6 months.

Contributions are welcome!

• Comprehensive API Coverage: Manage Ansible Tower resources including inventories, hosts, groups, job templates, projects, credentials, organizations, teams, users, ad hoc commands, workflows, and schedules.
• MCP Integration: Exposes Ansible Tower API functionalities as MCP tools for use with AI agents or direct API calls.
• Flexible Authentication: Supports both username/password and token-based authentication.
• Environment Variable Support: Securely configure credentials and settings via environment variables.
• Docker Support: Easily deployable as a Docker container for scalable environments.
• Extensive Documentation: Clear examples and instructions for setup, usage, and testing.

The ansible-tower-mcp package exposes the following MCP tools, organized by category:

• list_inventories(limit, offset): List all inventories.
• get_inventory(inventory_id): Get details of a specific inventory.
• create_inventory(name, organization_id, description): Create a new inventory.
• update_inventory(inventory_id, name, description): Update an existing inventory.
• delete_inventory(inventory_id): Delete an inventory.

• list_hosts(inventory_id, limit, offset): List hosts, optionally filtered by inventory.
• get_host(host_id): Get details of a specific host.
• create_host(name, inventory_id, variables, description): Create a new host.
• update_host(host_id, name, variables, description): Update an existing host.
• delete_host(host_id): Delete a host.

• list_groups(inventory_id, limit, offset): List groups in an inventory.
• get_group(group_id): Get details of a specific group.
• create_group(name, inventory_id, variables, description): Create a new group.
• update_group(group_id, name, variables, description): Update an existing group.
• delete_group(group_id): Delete a group.
• add_host_to_group(group_id, host_id): Add a host to a group.
• remove_host_from_group(group_id, host_id): Remove a host from a group.

• list_job_templates(limit, offset): List all job templates.
• get_job_template(template_id): Get details of a specific job template.
• create_job_template(name, inventory_id, project_id, playbook, credential_id, description, extra_vars): Create a new job template.
• update_job_template(template_id, name, inventory_id, playbook, description, extra_vars): Update an existing job template.
• delete_job_template(template_id): Delete a job template.
• launch_job(template_id, extra_vars): Launch a job from a template.

• list_jobs(status, limit, offset): List jobs, optionally filtered by status.
• get_job(job_id): Get details of a specific job.
• cancel_job(job_id): Cancel a running job.
• get_job_events(job_id, limit, offset): Get events for a job.
• get_job_stdout(job_id, format): Get the output of a job in specified format (txt, html, json, ansi).

• list_projects(limit, offset): List all projects.
• get_project(project_id): Get details of a specific project.
• create_project(name, organization_id, scm_type, scm_url, scm_branch, credential_id, description): Create a new project.
• update_project(project_id, name, scm_type, scm_url, scm_branch, description): Update an existing project.
• delete_project(project_id): Delete a project.
• sync_project(project_id): Sync a project with its SCM.

• list_credentials(limit, offset): List all credentials.
• get_credential(credential_id): Get details of a specific credential.
• list_credential_types(limit, offset): List all credential types.
• create_credential(name, credential_type_id, organization_id, inputs, description): Create a new credential.
• update_credential(credential_id, name, inputs, description): Update an existing credential.
• delete_credential(credential_id): Delete a credential.

• list_organizations(limit, offset): List all organizations.
• get_organization(organization_id): Get details of a specific organization.
• create_organization(name, description): Create a new organization.
• update_organization(organization_id, name, description): Update an existing organization.
• delete_organization(organization_id): Delete an organization.

• list_teams(organization_id, limit, offset): List teams, optionally filtered by organization.
• get_team(team_id): Get details of a specific team.
• create_team(name, organization_id, description): Create a new team.
• update_team(team_id, name, description): Update an existing team.
• delete_team(team_id): Delete a team.

• list_users(limit, offset): List all users.
• get_user(user_id): Get details of a specific user.
• create_user(username, password, first_name, last_name, email, is_superuser, is_system_auditor): Create a new user.
• update_user(user_id, username, password, first_name, last_name, email, is_superuser, is_system_auditor): Update an existing user.
• delete_user(user_id): Delete a user.

• run_ad_hoc_command(inventory_id, credential_id, module_name, module_args, limit, verbosity): Run an ad hoc command.
• get_ad_hoc_command(command_id): Get details of an ad hoc command.
• cancel_ad_hoc_command(command_id): Cancel an ad hoc command.

• list_workflow_templates(limit, offset): List all workflow templates.
• get_workflow_template(template_id): Get details of a specific workflow template.
• launch_workflow(template_id, extra_vars): Launch a workflow from a template.

• list_workflow_jobs(status, limit, offset): List workflow jobs, optionally filtered by status.
• get_workflow_job(job_id): Get details of a specific workflow job.
• cancel_workflow_job(job_id): Cancel a running workflow job.

• list_schedules(unified_job_template_id, limit, offset): List schedules, optionally filtered by job/workflow template.
• get_schedule(schedule_id): Get details of a specific schedule.
• create_schedule(name, unified_job_template_id, rrule, description, extra_data): Create a new schedule.
• update_schedule(schedule_id, name, rrule, description, extra_data): Update an existing schedule.
• delete_schedule(schedule_id): Delete a schedule.

• get_ansible_version(): Get the Ansible Tower version.
• get_dashboard_stats(): Get dashboard statistics.
• get_metrics(): Get system metrics.

---
config:
  layout: dagre
---
flowchart TB
 subgraph subGraph0["Agent Capabilities"]
        C["Agent"]
        B["A2A Server - Uvicorn/FastAPI"]
        D["MCP Tools"]
        F["Agent Skills"]
  end
    C --> D & F
    A["User Query"] --> B
    B --> C
    D --> E["Platform API"]

     C:::agent
     B:::server
     A:::server
    classDef server fill:#f9f,stroke:#333
    classDef agent fill:#bbf,stroke:#333,stroke-width:2px
    style B stroke:#000000,fill:#FFD600
    style D stroke:#000000,fill:#BBDEFB
    style F fill:#BBDEFB
    style A fill:#C8E6C9
    style subGraph0 fill:#FFF9C4

sequenceDiagram
    participant User
    participant Server as A2A Server
    participant Agent as Agent
    participant Skill as Agent Skills
    participant MCP as MCP Tools

    User->>Server: Send Query
    Server->>Agent: Invoke Agent
    Agent->>Skill: Analyze Skills Available
    Skill->>Agent: Provide Guidance on Next Steps
    Agent->>MCP: Invoke Tool
    MCP-->>Agent: Tool Response Returned
    Agent-->>Agent: Return Results Summarized
    Agent-->>Server: Final Response
    Server-->>User: Output

This agent uses pydantic-graph orchestration for intelligent routing and optimal context management.

---
title: Ansible Tower MCP Graph Agent
---
stateDiagram-v2
  [*] --> RouterNode: User Query
  RouterNode --> DomainNode: Classified Domain
  RouterNode --> [*]: Low confidence / Error
  DomainNode --> [*]: Domain Result

• RouterNode: A fast, lightweight LLM (e.g., nvidia/nemotron-3-super) that classifies the user's query into one of the specialized domains.
• DomainNode: The executor node. For the selected domain, it dynamically sets environment variables to temporarily enable ONLY the tools relevant to that domain, creating a highly focused sub-agent (e.g., gpt-4o) to complete the request. This preserves LLM context and prevents tool hallucination.

• Web UI: http://localhost:8000/ (if enabled)
• A2A: http://localhost:8000/a2a (Discovery: /a2a/.well-known/agent.json)
• AG-UI: http://localhost:8000/ag-ui (POST)

The MCP Server can be run in two modes: stdio (for local testing) or http (for networked access). To start the server, use the following commands:

ansible-tower-mcp

ansible-tower-mcp --transport http --host 0.0.0.0 --port 8012

Set environment variables for authentication:

export ANSIBLE_BASE_URL="https://your-ansible-tower-instance.com"
export ANSIBLE_USERNAME="your-username"
export ANSIBLE_PASSWORD="your-password"
# or
export ANSIBLE_TOKEN="your-api-token"
export VERIFY="False"  # Set to True to enable SSL verification

You can interact with the Ansible Tower API directly using the Api class from ansible_tower_api.py. Below is an example of creating an inventory and launching a job:

from ansible_tower_mcp.ansible_tower_api import Api

# Initialize the API client
client = Api(
    base_url="https://your-ansible-tower-instance.com",
    username="your-username",
    password="your-password",
    verify=False
)

# Create an inventory
inventory = client.create_inventory(
    name="Test Inventory",
    organization_id=1,
    description="A test inventory"
)
print(inventory)

# Launch a job from a job template
job = client.launch_job(template_id=123, extra_vars='{"key": "value"}')
print(job)

The ServiceNow MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.

docker pull knucklessg1/ansible-tower-mcp:latest

docker run -d \
  --name ansible-tower-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=none \
  -e EUNOMIA_TYPE=none \
  -e ANSIBLE_BASE_URL=https://your-ansible-tower-instance.com \
  -e ANSIBLE_USERNAME=your-username \
  -e ANSIBLE_PASSWORD=your-password \
  -e ANSIBLE_TOKEN=your-api-token \
  knucklessg1/ansible-tower-mcp:latest

For advanced authentication (e.g., JWT, OAuth Proxy, OIDC Proxy, Remote OAuth) or Eunomia, add the relevant environment variables:

docker run -d \
  --name ansible-tower-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=oidc-proxy \
  -e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
  -e OIDC_CLIENT_ID=your-client-id \
  -e OIDC_CLIENT_SECRET=your-client-secret \
  -e OIDC_BASE_URL=https://your-server.com \
  -e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
  -e EUNOMIA_TYPE=embedded \
  -e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
  -e ANSIBLE_BASE_URL=https://your-ansible-tower-instance.com \
  -e ANSIBLE_USERNAME=your-username \
  -e ANSIBLE_PASSWORD=your-password \
  -e ANSIBLE_TOKEN=your-api-token \
  knucklessg1/ansible-tower-mcp:latest

Create a docker-compose.yml file:

services:
  ansible-tower-mcp:
    image: knucklessg1/ansible-tower-mcp:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=http
      - AUTH_TYPE=none
      - EUNOMIA_TYPE=none
      - ANSIBLE_BASE_URL=https://your-ansible-tower-instance.com
      - ANSIBLE_USERNAME=your-username
      - ANSIBLE_PASSWORD=your-password
      - ANSIBLE_TOKEN=your-api-token
      - ANSIBLE_SSL_VERIFY=False
    ports:
      - 8004:8004

For advanced setups with authentication and Eunomia:

services:
  ansible-tower-mcp:
    image: knucklessg1/ansible-tower-mcp:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8004
      - TRANSPORT=http
      - AUTH_TYPE=oidc-proxy
      - OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
      - OIDC_CLIENT_ID=your-client-id
      - OIDC_CLIENT_SECRET=your-client-secret
      - OIDC_BASE_URL=https://your-server.com
      - ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
      - EUNOMIA_TYPE=embedded
      - EUNOMIA_POLICY_FILE=/app/mcp_policies.json
      - ANSIBLE_BASE_URL=https://your-ansible-tower-instance.com
      - ANSIBLE_USERNAME=your-username
      - ANSIBLE_PASSWORD=your-password
      - ANSIBLE_TOKEN=your-api-token
      - ANSIBLE_SSL_VERIFY=False
    ports:
      - 8004:8004
    volumes:
      - ./mcp_policies.json:/app/mcp_policies.json

Run the service:

docker-compose up -d

{
  "mcpServers": {
    "ansible-tower": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "ansible-tower-mcp>=0.0.4",
        "ansible-tower-mcp",
        "--transport",
        "stdio"
      ],
      "env": {
        "ANSIBLE_BASE_URL": "${ANSIBLE_BASE_URL}",
        "ANSIBLE_USERNAME": "${ANSIBLE_USERNAME}",
        "ANSIBLE_PASSWORD": "${ANSIBLE_PASSWORD}",
        "ANSIBLE_CLIENT_ID": "${ANSIBLE_CLIENT_ID}",
        "ANSIBLE_CLIENT_SECRET": "${ANSIBLE_CLIENT_SECRET}",
        "ANSIBLE_TOKEN": "${ANSIBLE_TOKEN}",
        "ANSIBLE_VERIFY": "${VERIFY:False}"
      },
      "timeout": 200000
    }
  }
}

Set environment variables:

export ANSIBLE_BASE_URL="https://your-ansible-tower-instance.com"
export ANSIBLE_USERNAME="your-username"
export ANSIBLE_PASSWORD="your-password"
export ANSIBLE_TOKEN="your-api-token"
export VERIFY="False"

For testing only, you can store credentials directly in mcp.json (not recommended for production):

{
  "mcpServers": {
    "ansible-tower": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "ansible-tower-mcp",
        "ansible-tower-mcp",
        "--transport",
        "http",
        "--host",
        "0.0.0.0",
        "--port",
        "8012"
      ],
      "env": {
        "ANSIBLE_BASE_URL": "https://your-ansible-tower-instance.com",
        "ANSIBLE_USERNAME": "your-username",
        "ANSIBLE_PASSWORD": "your-password",
        "ANSIBLE_TOKEN": "your-api-token",
        "VERIFY": "False"
      },
      "timeout": 200000
    }
  }
}

Install the ansible-tower-mcp package using pip:

python -m pip install ansible-tower-mcp[all]

Ensure the following Python packages are installed:

• requests
• fastmcp
• pydantic

Install dependencies manually if needed:

python -m pip install requests fastmcp pydantic

Run pre-commit checks to ensure code quality and formatting:

pre-commit run --all-files

To set up pre-commit hooks:

pre-commit install

Validate the MCP server configuration and tools using the MCP inspector:

npx @modelcontextprotocol/inspector ansible-tower-mcp

Run unit tests (if available in your project setup):

python -m pytest tests/

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/your-feature).
3. Make your changes and commit (git commit -m 'Add your feature').
4. Push to the branch (git push origin feature/your-feature).
5. Open a pull request.

Please ensure your code passes pre-commit checks and includes relevant tests.

This project is licensed under the MIT License. See the LICENSE file for details.

For issues or feature requests, please open an issue on the GitHub repository. For general inquiries, contact the maintainers via GitHub.