ansible-tower-mcp 1.13.1

Ansible Tower MCP Server for Agentic AI!

Ansible Tower API - A2A | AG-UI | MCP

Version: 1.13.1

Overview

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!

Features

• 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.

MCP

Available MCP Tools

This server utilizes dynamic Action-Routed tools to optimize token overhead and maximize IDE compatibility.

Tool Name	Description
ansible_ad_hoc_commands	Consolidated Action-Routed tool for ad_hoc_commands. Methods: run_ad_hoc_command, get_ad_hoc_command, cancel_ad_hoc_command
ansible_credentials	Consolidated Action-Routed tool for credentials. Methods: list_credentials, get_credential, list_credential_types, create_credential, update_credential, delete_credential
ansible_groups	Consolidated Action-Routed tool for groups. Methods: list_groups, get_group, create_group, update_group, delete_group, add_host_to_group, remove_host_from_group
ansible_hosts	Consolidated Action-Routed tool for hosts. Methods: list_hosts, get_host, create_host, update_host, delete_host
ansible_inventory	Consolidated Action-Routed tool for inventory. Methods: list_inventories, get_inventory, create_inventory, update_inventory, delete_inventory
ansible_job_templates	Consolidated Action-Routed tool for job-templates. Methods: list_job_templates, get_job_template, create_job_template, update_job_template, delete_job_template, launch_job
ansible_jobs	Consolidated Action-Routed tool for jobs. Methods: list_jobs, get_job, cancel_job, relaunch_job, get_job_events, get_job_stdout
ansible_organizations	Consolidated Action-Routed tool for organizations. Methods: list_organizations, get_organization, create_organization, update_organization, delete_organization
ansible_projects	Consolidated Action-Routed tool for projects. Methods: list_projects, get_project, create_project, update_project, delete_project, sync_project
ansible_schedules	Consolidated Action-Routed tool for schedules. Methods: list_schedules, get_schedule, create_schedule, update_schedule, delete_schedule
ansible_system	Consolidated Action-Routed tool for system. Methods: get_ansible_version, get_dashboard_stats, get_metrics
ansible_teams	Consolidated Action-Routed tool for teams. Methods: list_teams, get_team, create_team, update_team, delete_team
ansible_users	Consolidated Action-Routed tool for users. Methods: list_users, get_user, create_user, update_user, delete_user
ansible_workflow_jobs	Consolidated Action-Routed tool for workflow_jobs. Methods: list_workflow_jobs, get_workflow_job, cancel_workflow_job
ansible_workflow_templates	Consolidated Action-Routed tool for workflow_templates. Methods: list_workflow_templates, get_workflow_template, launch_workflow

A2A Agent

Architecture:

---
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

Component Interaction Diagram

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

Graph Architecture

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.

Usage

MCP CLI

Short Flag	Long Flag	Description
-h	--help	Display help information
-t	--transport	Transport method: 'stdio', 'http', or 'sse' [legacy] (default: stdio)
-s	--host	Host address for HTTP transport (default: 0.0.0.0)
-p	--port	Port number for HTTP transport (default: 8000)
	--auth-type	Authentication type: 'none', 'static', 'jwt', 'oauth-proxy', 'oidc-proxy', 'remote-oauth' (default: none)
	--oauth-upstream-client-id	Upstream client ID for OAuth Proxy
	--oauth-upstream-client-secret	Upstream client secret for OAuth Proxy
	--oauth-base-url	Base URL for OAuth Proxy
	--oidc-config-url	OIDC configuration URL
	--oidc-client-id	OIDC client ID
	--oidc-client-secret	OIDC client secret
	--oidc-base-url	Base URL for OIDC Proxy
	--remote-auth-servers	Comma-separated list of authorization servers for Remote OAuth
	--remote-base-url	Base URL for Remote OAuth
	--allowed-client-redirect-uris	Comma-separated list of allowed client redirect URIs
	--eunomia-type	Eunomia authorization type: 'none', 'embedded', 'remote' (default: none)
	--eunomia-policy-file	Policy file for embedded Eunomia (default: mcp_policies.json)
	--eunomia-remote-url	URL for remote Eunomia server

A2A CLI

Endpoints

• 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)

Long Flag	Description	Default
--host	Host to bind the server to	0.0.0.0
--port	Port to bind the server to	9000
--reload	Enable auto-reload	False
--provider	LLM Provider (openai, anthropic, google, etc)	openai
--model-id	LLM Model ID	nvidia/nemotron-3-super
--base-url	LLM Base URL (for OpenAI compatible providers)	http://host.docker.internal:1234/v1
--api-key	LLM API Key	ollama
--mcp-url	MCP Server URL to connect to	None
--mcp-config	MCP Server Config	.../mcp_config.json
--skills-directory	Directory containing agent skills	...
--web	Enable Pydantic AI Web UI	False (Env: ENABLE_WEB_UI)

Using as an MCP Server

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:

Run in stdio mode (default):

ansible-tower-mcp

Run in HTTP mode:

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

Use API Directly

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)

Deploy MCP Server as a Service

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

Using Docker Run

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

Using Docker Compose

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

Configure mcp.json for AI Integration

{
  "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
    }
  }
}

Security & Governance

This project is built on agent-utilities, inheriting enterprise-grade security and governance features.

Authentication & Authorization

Feature	Description
OIDC Token Delegation	RFC 8693 token exchange for user-context propagation from A2A → MCP
Eunomia Policies	Fine-grained, policy-driven tool authorization (none, embedded, remote)
Scoped Credentials	Tools execute with the caller's scoped identity where possible
3LO / OAuth / API Token	Multiple auth strategies with graceful fallback

Eunomia Policy Enforcement

Eunomia provides a policy enforcement point for all tool calls:

• Embedded mode: Load local mcp_policies.json for role-based access, sensitivity gating, and audit logging
• Remote mode: Forward authorization decisions to a central Eunomia policy server for multi-agent governance
• Enable via CLI: --eunomia-type embedded --eunomia-policy-file mcp_policies.json

Runtime Protections

Protection	Description
Tool Guard	Sensitivity detection with human-in-the-loop approval gating
Prompt Injection Defense	Input scanning and repetition/loop guards
Content Filtering	Output schema enforcement and cost budget controls
Stuck Loop Detection	Automatic detection and recovery from agent loops
Context Limit Warnings	Proactive alerts before context window exhaustion

Graph Agent Architecture

The A2A agent uses pydantic-graph orchestration with:

• RouterNode: Lightweight classifier that routes queries to specialized domains
• DomainNode: Focused executor with only relevant tools loaded, preventing tool hallucination
• Approval Gates: Policy-driven approval workflows before sensitive operations
• Usage Guards: Budget and rate limiting enforcement

Production Recommendation: Enable --eunomia-type embedded (or remote) + OIDC delegation + containerized deployment. See agent-utilities documentation for full policy configuration.

Install Python Package

Install the ansible-tower-mcp package using pip:

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

Dependencies

Ensure the following Python packages are installed:

• requests
• fastmcp
• pydantic

Install dependencies manually if needed:

python -m pip install requests fastmcp pydantic

Tests

Pre-commit Checks

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 MCP Server

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

npx @modelcontextprotocol/inspector ansible-tower-mcp

Unit Tests

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

python -m pytest tests/

Repository Owners

Contributing

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.

License

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

Support

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

MCP Configuration Examples

stdio (recommended for local development)

{
  "mcpServers": {
    "ansible-tower": {
      "command": ".venv/bin/ansible-tower-mcp",
      "args": [],
      "env": {
        "ANSIBLE_BASE_URL": "",
        "ANSIBLE_USERNAME": "",
        "ANSIBLE_PASSWORD": ""
}
    }
  }
}

Streamable HTTP (recommended for production)

{
  "mcpServers": {
    "ansible-tower": {
      "url": "http://localhost:8080/ansible-tower-mcp/mcp"
    }
  }
}