Ansible Tower MCP Server for Agentic AI!

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Knucklessg1 from gravatar.com Knucklessg1

Unverified details

These details have not been verified by PyPI
Meta
  • License: Public Domain (MIT)
  • Author: Audel Rouhi
  • Requires: Python <3.15, >=3.11
  • Provides-Extra: mcp , agent , all , test
Classifiers
Report project as malware

Project description

Ansible Tower Mcp

CLI or API | MCP | Agent

PyPI - Version MCP Server PyPI - Downloads GitHub Repo stars GitHub forks GitHub contributors PyPI - License GitHub GitHub last commit (by committer) GitHub pull requests GitHub closed pull requests GitHub issues GitHub top language GitHub language count GitHub repo size GitHub repo file count (file type) PyPI - Wheel PyPI - Implementation

Version: 2.0.1

Documentation — Installation, deployment, and usage across the API, CLI, MCP, and A2A agent interfaces are maintained in the official documentation.

Overview

Ansible Tower Mcp is a production-grade Agent and Model Context Protocol (MCP) server designed to interface directly with Ansible Tower MCP Server for Agentic AI!.

Key Features

  • Consolidated Action-Routed MCP Tools: Minimizes token overhead and eliminates tool bloat in LLM contexts by grouping methods into optimized, togglable tool modules.
  • Enterprise-Grade Security: Comprehensive support for Eunomia policies, OIDC token delegation, and granular execution context tracking.
  • Integrated Graph Agent: Built-in Pydantic AI agent supporting the Agent Control Protocol (ACP) and standard Web interfaces (AG-UI).
  • Native Telemetry & Tracing: Out-of-the-box OpenTelemetry exports and native Langfuse tracing.

CLI or API

This agent wraps the Ansible Tower MCP Server for Agentic AI! API. You can interact with it programmatically or via its integrated execution entrypoints.

Detailed instructions on how to use the underlying API wrappers, extended schema bindings, and developer SDK references are maintained in docs/index.md.

MCP

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

Available MCP Tools

The table below is auto-generated from the live server — do not edit by hand.

Condensed action-routed tools (default — MCP_TOOL_MODE=condensed)

MCP Tool Toggle Env Var Description
ansible_tower_ad_hoc_commands AD_HOC_COMMANDSTOOL Manage ansible tower ad hoc commands operations.
ansible_tower_credentials CREDENTIALSTOOL Manage ansible tower credentials operations.
ansible_tower_groups GROUPSTOOL Manage ansible tower groups operations.
ansible_tower_hosts HOSTSTOOL Manage ansible tower hosts operations.
ansible_tower_inventory INVENTORYTOOL Manage ansible tower inventory operations.
ansible_tower_job_templates JOB_TEMPLATESTOOL Manage ansible tower job templates operations.
ansible_tower_jobs JOBSTOOL Manage ansible tower jobs operations.
ansible_tower_organizations ORGANIZATIONSTOOL Manage ansible tower organizations operations.
ansible_tower_projects PROJECTSTOOL Manage ansible tower projects operations.
ansible_tower_schedules SCHEDULESTOOL Manage ansible tower schedules operations.
ansible_tower_system SYSTEMTOOL Manage ansible tower system operations.
ansible_tower_teams TEAMSTOOL Manage ansible tower teams operations.
ansible_tower_users USERSTOOL Manage ansible tower users operations.
ansible_tower_workflow_jobs WORKFLOW_JOBSTOOL Manage ansible tower workflow jobs operations.
ansible_tower_workflow_templates WORKFLOW_TEMPLATESTOOL Manage ansible tower workflow templates operations.

Verbose 1:1 API-mapped tools (MCP_TOOL_MODE=verbose or both)

76 per-operation tools — one per public API method (click to expand)
MCP Tool Toggle Env Var Description
ansible_tower_add_host_to_group APITOOL Invoke the add_host_to_group operation.
ansible_tower_cancel_ad_hoc_command APITOOL Invoke the cancel_ad_hoc_command operation.
ansible_tower_cancel_job APITOOL Invoke the cancel_job operation.
ansible_tower_cancel_workflow_job APITOOL Invoke the cancel_workflow_job operation.
ansible_tower_create_credential APITOOL Invoke the create_credential operation.
ansible_tower_create_group APITOOL Invoke the create_group operation.
ansible_tower_create_host APITOOL Invoke the create_host operation.
ansible_tower_create_inventory APITOOL Invoke the create_inventory operation.
ansible_tower_create_job_template APITOOL Invoke the create_job_template operation.
ansible_tower_create_organization APITOOL Invoke the create_organization operation.
ansible_tower_create_project APITOOL Invoke the create_project operation.
ansible_tower_create_schedule APITOOL Invoke the create_schedule operation.
ansible_tower_create_team APITOOL Invoke the create_team operation.
ansible_tower_create_user APITOOL Invoke the create_user operation.
ansible_tower_delete_credential APITOOL Invoke the delete_credential operation.
ansible_tower_delete_group APITOOL Invoke the delete_group operation.
ansible_tower_delete_host APITOOL Invoke the delete_host operation.
ansible_tower_delete_inventory APITOOL Invoke the delete_inventory operation.
ansible_tower_delete_job_template APITOOL Invoke the delete_job_template operation.
ansible_tower_delete_organization APITOOL Invoke the delete_organization operation.
ansible_tower_delete_project APITOOL Invoke the delete_project operation.
ansible_tower_delete_schedule APITOOL Invoke the delete_schedule operation.
ansible_tower_delete_team APITOOL Invoke the delete_team operation.
ansible_tower_delete_user APITOOL Invoke the delete_user operation.
ansible_tower_get_ad_hoc_command APITOOL Invoke the get_ad_hoc_command operation.
ansible_tower_get_ansible_version APITOOL Invoke the get_ansible_version operation.
ansible_tower_get_credential APITOOL Invoke the get_credential operation.
ansible_tower_get_dashboard_stats APITOOL Invoke the get_dashboard_stats operation.
ansible_tower_get_group APITOOL Invoke the get_group operation.
ansible_tower_get_headers BASE_API_CLIENTTOOL Get request headers with authorization.
ansible_tower_get_host APITOOL Invoke the get_host operation.
ansible_tower_get_inventory APITOOL Invoke the get_inventory operation.
ansible_tower_get_job APITOOL Invoke the get_job operation.
ansible_tower_get_job_events APITOOL Invoke the get_job_events operation.
ansible_tower_get_job_stdout APITOOL Invoke the get_job_stdout operation.
ansible_tower_get_job_template APITOOL Invoke the get_job_template operation.
ansible_tower_get_metrics APITOOL Invoke the get_metrics operation.
ansible_tower_get_organization APITOOL Invoke the get_organization operation.
ansible_tower_get_project APITOOL Invoke the get_project operation.
ansible_tower_get_schedule APITOOL Invoke the get_schedule operation.
ansible_tower_get_team APITOOL Invoke the get_team operation.
ansible_tower_get_token BASE_API_CLIENTTOOL Authenticate and get token using web session approach.
ansible_tower_get_user APITOOL Invoke the get_user operation.
ansible_tower_get_workflow_job APITOOL Invoke the get_workflow_job operation.
ansible_tower_get_workflow_template APITOOL Invoke the get_workflow_template operation.
ansible_tower_handle_pagination BASE_API_CLIENTTOOL Handle paginated results from Ansible API.
ansible_tower_launch_job APITOOL Invoke the launch_job operation.
ansible_tower_launch_workflow APITOOL Invoke the launch_workflow operation.
ansible_tower_list_credential_types APITOOL Invoke the list_credential_types operation.
ansible_tower_list_credentials APITOOL Invoke the list_credentials operation.
ansible_tower_list_groups APITOOL Invoke the list_groups operation.
ansible_tower_list_hosts APITOOL Invoke the list_hosts operation.
ansible_tower_list_inventories APITOOL Invoke the list_inventories operation.
ansible_tower_list_job_templates APITOOL Invoke the list_job_templates operation.
ansible_tower_list_jobs APITOOL Invoke the list_jobs operation.
ansible_tower_list_organizations APITOOL Invoke the list_organizations operation.
ansible_tower_list_projects APITOOL Invoke the list_projects operation.
ansible_tower_list_schedules APITOOL Invoke the list_schedules operation.
ansible_tower_list_teams APITOOL Invoke the list_teams operation.
ansible_tower_list_users APITOOL Invoke the list_users operation.
ansible_tower_list_workflow_jobs APITOOL Invoke the list_workflow_jobs operation.
ansible_tower_list_workflow_templates APITOOL Invoke the list_workflow_templates operation.
ansible_tower_remove_host_from_group APITOOL Invoke the remove_host_from_group operation.
ansible_tower_request BASE_API_CLIENTTOOL Make a request to the Ansible API.
ansible_tower_run_ad_hoc_command APITOOL Invoke the run_ad_hoc_command operation.
ansible_tower_sync_project APITOOL Invoke the sync_project operation.
ansible_tower_update_credential APITOOL Invoke the update_credential operation.
ansible_tower_update_group APITOOL Invoke the update_group operation.
ansible_tower_update_host APITOOL Invoke the update_host operation.
ansible_tower_update_inventory APITOOL Invoke the update_inventory operation.
ansible_tower_update_job_template APITOOL Invoke the update_job_template operation.
ansible_tower_update_organization APITOOL Invoke the update_organization operation.
ansible_tower_update_project APITOOL Invoke the update_project operation.
ansible_tower_update_schedule APITOOL Invoke the update_schedule operation.
ansible_tower_update_team APITOOL Invoke the update_team operation.
ansible_tower_update_user APITOOL Invoke the update_user operation.

15 action-routed tool(s) (default) · 76 verbose 1:1 tool(s). Each is enabled unless its <DOMAIN>TOOL toggle is set false; MCP_TOOL_MODE selects the surface (condensed default · verbose 1:1 · both). Auto-generated — do not edit.

Detailed tool schemas, parameter shapes, and validation constraints are preserved in docs/mcp.md.

Dynamic Tool Selection & Visibility

This MCP server supports dynamic toolset selection and visibility filtering at runtime. This allows you to restrict the set of exposed tools in order to prevent blowing up the LLM's context window.

You can configure tool filtering via multiple input channels:

  • CLI Arguments: Pass --tools or --toolsets (or their disabled counterparts --disabled-tools and --disabled-toolsets) during startup.
  • Environment Variables: Define standard environment variables:
    • MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS
    • MCP_ENABLED_TAGS / MCP_DISABLED_TAGS
  • HTTP SSE Request Headers: Pass custom headers during transport initialization:
    • x-mcp-enabled-tools / x-mcp-disabled-tools
    • x-mcp-enabled-tags / x-mcp-disabled-tags
  • HTTP SSE Request Query Parameters: Append query parameters directly to your transport connection URL:
    • ?tools=tool1,tool2
    • ?tags=tag1

When query strings or parameters are supplied, an LLM-free Knowledge Graph resolution layer (using DynamicToolOrchestrator) matches query intents against known tool tags, names, or descriptions, with safe fallback and automated 24-hour background cache refreshing.

MCP Configuration Examples

Install the slim [mcp] extra. All examples install ansible-tower-mcp[mcp] — the MCP-server extra that pulls only the FastMCP / FastAPI tooling (agent-utilities[mcp]). It deliberately excludes the heavy agent runtime (pydantic-ai, the epistemic-graph engine, dspy, llama-index), so uvx / container installs are far smaller. Use the full [agent] extra only when you need the integrated Pydantic AI agent.

stdio Transport (local IDEs — Cursor, Claude Desktop, VS Code)

{
  "mcpServers": {
    "ansible-tower-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "ansible-tower-mcp[mcp]",
        "ansible-tower-mcp"
      ],
      "env": {
        "MCP_TOOL_MODE": "condensed",
        "AD_HOC_COMMANDSTOOL": "True",
        "ANSIBLE_BASE_URL": "https://ansible.example.com",
        "ANSIBLE_CLIENT_ID": "<YOUR_ANSIBLE_CLIENT_ID>",
        "ANSIBLE_CLIENT_SECRET": "<YOUR_ANSIBLE_CLIENT_SECRET>",
        "ANSIBLE_PASSWORD": "<YOUR_ANSIBLE_PASSWORD>",
        "ANSIBLE_USERNAME": "<YOUR_ANSIBLE_USERNAME>",
        "ANSIBLE_VERIFY": "False",
        "AUDIENCE": "",
        "CREDENTIALSTOOL": "True",
        "DELEGATED_SCOPES": "api",
        "GROUPSTOOL": "True",
        "HOSTSTOOL": "True",
        "INVENTORYTOOL": "True",
        "JOBSTOOL": "True",
        "JOB_TEMPLATESTOOL": "True",
        "ORGANIZATIONSTOOL": "True",
        "PROJECTSTOOL": "True",
        "SCHEDULESTOOL": "True",
        "SYSTEMTOOL": "True",
        "TEAMSTOOL": "True",
        "USERSTOOL": "True",
        "WORKFLOW_JOBSTOOL": "True",
        "WORKFLOW_TEMPLATESTOOL": "True"
      }
    }
  }
}

Streamable-HTTP Transport (networked / production)

{
  "mcpServers": {
    "ansible-tower-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "ansible-tower-mcp[mcp]",
        "ansible-tower-mcp",
        "--transport",
        "streamable-http",
        "--port",
        "8000"
      ],
      "env": {
        "TRANSPORT": "streamable-http",
        "HOST": "0.0.0.0",
        "PORT": "8000",
        "MCP_TOOL_MODE": "condensed",
        "AD_HOC_COMMANDSTOOL": "True",
        "ANSIBLE_BASE_URL": "https://ansible.example.com",
        "ANSIBLE_CLIENT_ID": "<YOUR_ANSIBLE_CLIENT_ID>",
        "ANSIBLE_CLIENT_SECRET": "<YOUR_ANSIBLE_CLIENT_SECRET>",
        "ANSIBLE_PASSWORD": "<YOUR_ANSIBLE_PASSWORD>",
        "ANSIBLE_USERNAME": "<YOUR_ANSIBLE_USERNAME>",
        "ANSIBLE_VERIFY": "False",
        "AUDIENCE": "",
        "CREDENTIALSTOOL": "True",
        "DELEGATED_SCOPES": "api",
        "GROUPSTOOL": "True",
        "HOSTSTOOL": "True",
        "INVENTORYTOOL": "True",
        "JOBSTOOL": "True",
        "JOB_TEMPLATESTOOL": "True",
        "ORGANIZATIONSTOOL": "True",
        "PROJECTSTOOL": "True",
        "SCHEDULESTOOL": "True",
        "SYSTEMTOOL": "True",
        "TEAMSTOOL": "True",
        "USERSTOOL": "True",
        "WORKFLOW_JOBSTOOL": "True",
        "WORKFLOW_TEMPLATESTOOL": "True"
      }
    }
  }
}

Alternatively, connect to a pre-deployed Streamable-HTTP instance by url:

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

Deploying the Streamable-HTTP server via Docker:

docker run -d \
  --name ansible-tower-mcp-mcp \
  -p 8000:8000 \
  -e TRANSPORT=streamable-http \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e MCP_TOOL_MODE=condensed \
  -e AD_HOC_COMMANDSTOOL=True \
  -e ANSIBLE_BASE_URL=https://ansible.example.com \
  -e ANSIBLE_CLIENT_ID="<YOUR_ANSIBLE_CLIENT_ID>" \
  -e ANSIBLE_CLIENT_SECRET="<YOUR_ANSIBLE_CLIENT_SECRET>" \
  -e ANSIBLE_PASSWORD="<YOUR_ANSIBLE_PASSWORD>" \
  -e ANSIBLE_USERNAME="<YOUR_ANSIBLE_USERNAME>" \
  -e ANSIBLE_VERIFY=False \
  -e AUDIENCE="" \
  -e CREDENTIALSTOOL=True \
  -e DELEGATED_SCOPES=api \
  -e GROUPSTOOL=True \
  -e HOSTSTOOL=True \
  -e INVENTORYTOOL=True \
  -e JOBSTOOL=True \
  -e JOB_TEMPLATESTOOL=True \
  -e ORGANIZATIONSTOOL=True \
  -e PROJECTSTOOL=True \
  -e SCHEDULESTOOL=True \
  -e SYSTEMTOOL=True \
  -e TEAMSTOOL=True \
  -e USERSTOOL=True \
  -e WORKFLOW_JOBSTOOL=True \
  -e WORKFLOW_TEMPLATESTOOL=True \
  knucklessg1/ansible-tower-mcp:mcp

Auto-generated from the code-read env surface (MCP_TOOL_MODE + package vars) — do not edit.

Additional Deployment Options

ansible-tower-mcp can also run as a local container (Docker / Podman / uv) or be consumed from a remote deployment. The Deployment guide has full, copy-paste mcp_config.json for all four transports — stdio, streamable-http, local container / uv, and remote URL:

  • Local container / uv — launch the server from mcp_config.json via uvx, docker run, or podman run, or point at a local streamable-http container by url.
  • Remote URL — connect to a server deployed behind Caddy at http://ansible-tower-mcp.arpa/mcp using the "url" key.

Environment Variables

Package environment variables

Variable Example Description
HOST 0.0.0.0
PORT 8000
TRANSPORT stdio options: stdio, streamable-http, sse
ANSIBLE_BASE_URL https://ansible.example.com Ansible Tower / AWX base URL
ANSIBLE_VERIFY False verify TLS certificates (True/False)
ANSIBLE_USERNAME <YOUR_ANSIBLE_USERNAME> Path 3: username / password auth
ANSIBLE_PASSWORD <YOUR_ANSIBLE_PASSWORD>
ANSIBLE_CLIENT_ID <YOUR_ANSIBLE_CLIENT_ID> Path 2: OAuth client-credentials auth
ANSIBLE_CLIENT_SECRET <YOUR_ANSIBLE_CLIENT_SECRET>
AUDIENCE — token-exchange audience (defaults to ANSIBLE_BASE_URL)
DELEGATED_SCOPES api space-delimited delegated scopes
ENABLE_OTEL True
OTEL_EXPORTER_OTLP_ENDPOINT http://localhost:8080/api/public/otel
OTEL_EXPORTER_OTLP_PUBLIC_KEY pk-...
OTEL_EXPORTER_OTLP_SECRET_KEY sk-...
OTEL_EXPORTER_OTLP_PROTOCOL http/protobuf
EUNOMIA_TYPE none options: none, embedded, remote
EUNOMIA_POLICY_FILE mcp_policies.json
EUNOMIA_REMOTE_URL http://eunomia-server:8000
INVENTORYTOOL True
HOSTSTOOL True
GROUPSTOOL True
JOB_TEMPLATESTOOL True
JOBSTOOL True
PROJECTSTOOL True
CREDENTIALSTOOL True
ORGANIZATIONSTOOL True
TEAMSTOOL True
USERSTOOL True
AD_HOC_COMMANDSTOOL True
WORKFLOW_TEMPLATESTOOL True
WORKFLOW_JOBSTOOL True
SCHEDULESTOOL True
SYSTEMTOOL True

Inherited agent-utilities variables (apply to every connector)

Variable Example Description
MCP_TOOL_MODE condensed Tool surface: condensed
MCP_ENABLED_TOOLS — Comma-separated tool allow-list
MCP_DISABLED_TOOLS — Comma-separated tool deny-list
MCP_ENABLED_TAGS — Comma-separated tag allow-list
MCP_DISABLED_TAGS — Comma-separated tag deny-list
MCP_CLIENT_AUTH — Outbound MCP auth (oidc-client-credentials for fleet calls)
OIDC_CLIENT_ID — OIDC client id (service-account auth)
OIDC_CLIENT_SECRET — OIDC client secret (service-account auth)
DEBUG False Verbose logging
PYTHONUNBUFFERED 1 Unbuffered stdout (recommended in containers)
MCP_URL http://localhost:8000/mcp URL of the MCP server the agent connects to
PROVIDER openai LLM provider for the agent
MODEL_ID gpt-4o Model id for the agent
ENABLE_WEB_UI True Serve the AG-UI web interface

34 package + 14 inherited variable(s). Auto-generated from .env.example + the shared agent-utilities set — do not edit.

Every variable the server reads, grouped by concern.

Connection & Credentials

Variable Description Default
ANSIBLE_BASE_URL Base URL of the Ansible Tower / AWX instance —
ANSIBLE_VERIFY TLS certificate verification False
ANSIBLE_CLIENT_ID OAuth application client id —
ANSIBLE_CLIENT_SECRET OAuth application client secret —
ANSIBLE_USERNAME Username (username/password fallback auth) —
ANSIBLE_PASSWORD Password (username/password fallback auth) —

Authentication mode

Resolved in priority order (first match wins).

Variable Auth mode Notes
ENABLE_DELEGATION 1. OIDC delegation (RFC 8693 token exchange) Set true to flow the caller's IdP token through to Ansible Tower
OIDC_CONFIG_URL / OIDC_CLIENT_ID / OIDC_CLIENT_SECRET OIDC delegation IdP config Required when delegation is enabled
AUDIENCE OIDC delegation token audience Defaults to ANSIBLE_BASE_URL
DELEGATED_SCOPES OIDC delegation scopes api
ANSIBLE_CLIENT_ID (+ ANSIBLE_CLIENT_SECRET) 2. OAuth client credentials Used when both are set
ANSIBLE_USERNAME (+ ANSIBLE_PASSWORD) 3. Username / password (fallback) Native token-based auth

MCP server / transport

Variable Description Default
TRANSPORT stdio, streamable-http, or sse stdio
HOST Bind host (HTTP transports) 0.0.0.0
PORT Bind port (HTTP transports) 8000
MCP_TOOL_MODE Tool surface: condensed, verbose, or both condensed
MCP_ENABLED_TOOLS / MCP_DISABLED_TOOLS Comma-separated tool allow/deny list —
MCP_ENABLED_TAGS / MCP_DISABLED_TAGS Comma-separated tag allow/deny list —
DEBUG Verbose logging False
PYTHONUNBUFFERED Unbuffered stdout (recommended in containers) 1

Tool toggles

Each action-routed tool can be disabled individually via its toggle env var (set to false). The full list is in the Available MCP Tools table above (e.g. JOBSTOOL, INVENTORYTOOL, JOB_TEMPLATESTOOL).

Telemetry & governance

Variable Description Default
ENABLE_OTEL Enable OpenTelemetry export True
OTEL_EXPORTER_OTLP_ENDPOINT OTLP collector endpoint —
OTEL_EXPORTER_OTLP_PUBLIC_KEY / OTEL_EXPORTER_OTLP_SECRET_KEY OTLP auth keys —
OTEL_EXPORTER_OTLP_PROTOCOL OTLP protocol (e.g. http/protobuf) —
EUNOMIA_TYPE Authorization mode: none, embedded, remote none
EUNOMIA_POLICY_FILE Embedded policy file mcp_policies.json
EUNOMIA_REMOTE_URL Remote Eunomia server URL —

Agent CLI (full [agent] runtime only)

Variable Description Default
MCP_URL URL of the MCP server the agent connects to http://localhost:8000/mcp
PROVIDER LLM provider (e.g. openai) openai
MODEL_ID Model id (e.g. gpt-4o) gpt-4o
ENABLE_WEB_UI Serve the AG-UI web interface True

See .env.example for a copy-paste starting point.

Agent

This repository features a fully integrated Pydantic AI Graph Agent. It communicates over the Agent Control Protocol (ACP) and interacts seamlessly with the Agent Web UI (AG-UI) and Terminal interface.

Running the Agent CLI

To start the interactive command-line agent:

# Set credentials

# Run the agent server
ansible-tower-agent --provider openai --model-id gpt-4o

Docker Compose Orchestration

The following docker/agent.compose.yml configures the Agent, Web UI, and Terminal Interface together:

version: '3.8'

services:
  ansible-tower-mcp-mcp:
    image: knucklessg1/ansible-tower-mcp:mcp
    container_name: ansible-tower-mcp-mcp
    hostname: ansible-tower-mcp-mcp
    restart: always
    env_file:
      - ../.env
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=8000
      - TRANSPORT=streamable-http
    ports:
      - "8000:8000"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

  ansible-tower-mcp-agent:
    image: knucklessg1/ansible-tower-mcp:latest
    container_name: ansible-tower-mcp-agent
    hostname: ansible-tower-mcp-agent
    restart: always
    depends_on:
      - ansible-tower-mcp-mcp
    env_file:
      - ../.env
    command: [ "ansible-tower-agent" ]
    environment:
      - PYTHONUNBUFFERED=1
      - HOST=0.0.0.0
      - PORT=9012
      - MCP_URL=http://ansible-tower-mcp-mcp:8000/mcp
      - PROVIDER=${PROVIDER:-openai}
      - MODEL_ID=${MODEL_ID:-gpt-4o}
      - ENABLE_WEB_UI=True
      - ENABLE_OTEL=True
    ports:
      - "9012:9012"
    healthcheck:
      test: ["CMD", "python3", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:9012/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

Detailed graph node architecture explanations, custom skill configurations, and agentic trace guides are available in docs/agent.md.

Security & Governance

Built directly upon the enterprise-ready agent-utilities core, standard security parameters are fully supported:

Access Control & Policy Enforcement

  • Eunomia Policies: Fine-grained, policy-driven tool authorization. Supports none, local embedded (mcp_policies.json), or centralized remote modes.
  • OIDC Token Delegation: Compliant with RFC 8693 token exchange for flowing authenticating user credentials from Web UI / ACP → Agent → MCP.
  • Scoped Credentials: Execution context runs restricted to the specific caller identity.

Runtime Security Grid

Feature Functionality Enablement
Tool Guard Sensitivity inspection with human-in-the-loop validation Enabled by default
Prompt Injection Defense Input scanning, repetition monitoring, and recursive loop blocks Enabled by default
Context Safety Guard Stuck-loop detectors and contextual overflow preemptive alerts Enabled by default

Installation

Pick the extra that matches what you want to run:

Extra Installs Use when
ansible-tower-mcp[mcp] Slim MCP server only (agent-utilities[mcp] — FastMCP/FastAPI) You only run the MCP server (smallest install / image)
ansible-tower-mcp[agent] Full agent runtime (agent-utilities[agent,logfire] — Pydantic AI + the epistemic-graph engine) You run the integrated agent
ansible-tower-mcp[all] Everything (mcp + agent + logfire) Development / both surfaces 
# MCP server only (recommended for tool hosting — slim deps)
uv pip install "ansible-tower-mcp[mcp]"

# Full agent runtime (Pydantic AI + epistemic-graph engine)
uv pip install "ansible-tower-mcp[agent]"

# Everything (development)
uv pip install "ansible-tower-mcp[all]"      # or: python -m pip install "ansible-tower-mcp[all]"

Container images (:mcp vs :agent)

One multi-stage docker/Dockerfile builds two right-sized images, selected by --target:

Image tag Build target Contents Entrypoint
knucklessg1/ansible-tower-mcp:mcp --target mcp ansible-tower-mcp[mcp] — slim, no engine/pydantic-ai/dspy/llama-index/tree-sitter ansible-tower-mcp
knucklessg1/ansible-tower-mcp:latest --target agent (default) ansible-tower-mcp[agent] — full agent runtime + epistemic-graph engine ansible-tower-agent 
docker build --target mcp   -t knucklessg1/ansible-tower-mcp:mcp    docker/   # slim MCP server
docker build --target agent -t knucklessg1/ansible-tower-mcp:latest docker/   # full agent

docker/mcp.compose.yml runs the slim :mcp server; docker/agent.compose.yml runs the agent (:latest) with a co-located :mcp sidecar.

Knowledge-graph database (epistemic-graph)

The full agent ([agent] / :latest) embeds the epistemic-graph engine (pulled in transitively via agent-utilities[agent]). For production — or to share one knowledge graph across multiple agents — run epistemic-graph as its own database container and point the agent at it instead of embedding it. Deployment recipes (single-node + Raft HA), connection config, and the full database architecture (with diagrams) are documented in the epistemic-graph deployment guide. The slim [mcp] server does not require the database.

Documentation

The complete documentation is published as the official documentation site and is the recommended reference for installation, deployment, and day-to-day operation.

Page Contents
Installation pip, source, extras, prebuilt Docker image
Deployment run the MCP and agent servers, Compose, Caddy + Technitium, env config
Usage the MCP tools, the Api client, the CLI
Overview ecosystem role, concept registry, architecture
Concepts concept registry (CONCEPT:ANSIBLE-*)

Repository Owners

GitHub followers GitHub User's stars

Contribute

Contributions are welcome! Please ensure code quality by executing local checks before submitting pull requests:

  • Format code using ruff format .
  • Lint code using ruff check .
  • Validate type-safety with mypy .
  • Execute test suites using pytest

Deploy with agent-os-genesis

This package can be provisioned for you — skill-guided — by the agent-os-genesis universal skill (its single-package deploy mode): it picks your install method, seeds secrets to OpenBao/Vault (or .env), trusts your enterprise CA, registers the MCP server, and verifies it — the same machinery that stands up the whole Agent OS, narrowed to just this package. Ask your agent to "deploy ansible-tower-mcp with agent-os-genesis".

Install mode Command
Bare-metal, prod (PyPI) uvx ansible-tower-mcp · or uv tool install ansible-tower-mcp
Bare-metal, dev (editable) uv pip install -e ".[all]" · or pip install -e ".[all]"
Container, prod deploy knucklessg1/ansible-tower-mcp:latest via docker-compose / swarm / podman / podman-compose / kubernetes
Container, dev (editable) deploy docker/compose.dev.yml (source-mounted at /src; edits live on restart)

Secrets are read-existing + seeded via vault_sync — you are only prompted for what's missing.

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for Knucklessg1 from gravatar.com Knucklessg1

Unverified details

These details have not been verified by PyPI
Meta
  • License: Public Domain (MIT)
  • Author: Audel Rouhi
  • Requires: Python <3.15, >=3.11
  • Provides-Extra: mcp , agent , all , test
Classifiers

Release history Release notifications | RSS feed

This version

2.0.1

1.36.0

1.34.0

1.33.0

1.32.0

1.31.0

1.29.0

1.27.0

1.26.0

1.25.0

1.23.0

1.21.0

1.16.0

1.13.1

1.13.0

1.12.0

1.11.0

1.10.0

1.8.2

1.4.0

1.3.54

1.3.53

1.3.47

1.3.45

1.3.44

1.3.41

1.3.40

1.3.39

1.3.32

1.3.31

1.3.28

1.3.27

1.3.25

1.3.24

1.3.23

1.3.22

1.3.21

1.3.20

1.3.19

1.3.18

1.3.17

1.3.16

1.3.15

1.3.14

1.3.13

1.3.12

1.3.11

1.3.10

1.3.9

1.3.8

1.3.7

1.3.6

1.3.5

1.3.4

1.3.2

1.3.1

1.2.28

1.2.27

1.2.26

1.2.25

1.2.24

1.2.23

1.2.22

1.2.21

1.2.20

1.2.19

1.2.18

1.2.17

1.2.16

1.2.15

1.2.14

1.2.13

1.2.12

1.2.10

1.2.9

1.2.8

1.2.7

1.2.6

1.2.5

1.2.4

1.2.3

1.2.2

1.2.1

1.2.0

1.1.0

1.0.0

0.0.7

0.0.6

0.0.5

0.0.4

0.0.3

0.0.2

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ansible_tower_mcp-2.0.1.tar.gz (77.8 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

ansible_tower_mcp-2.0.1-py3-none-any.whl (56.1 kB view details)

Uploaded Python 3

File details

Details for the file ansible_tower_mcp-2.0.1.tar.gz.

File metadata

  • Download URL: ansible_tower_mcp-2.0.1.tar.gz
  • Upload date:
  • Size: 77.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.14.4

File hashes

Hashes for ansible_tower_mcp-2.0.1.tar.gz
Algorithm Hash digest
SHA256 a25362869f0fe75999397cc2ff1bf511da8ddf1ea8ed6079be928b67faabdd49
MD5 eefdafd4ca1dc895432bebbd948e8f44
BLAKE2b-256 1558b6917241fbeb3e177b74be56bc173fdc97b56ab65e1ecdaaaf432c399240

See more details on using hashes here.

File details

Details for the file ansible_tower_mcp-2.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for ansible_tower_mcp-2.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 8563fd3f2cc3fdc866409f726f42ce1707503cdf7800081935fea8be9c472d5e
MD5 a1e3dc8755989ddfbf33daf128183ab6
BLAKE2b-256 0d4c0aa91ee79bddf9ce75012a8566568284d7a4bc13d12961ef4efe9e115c91

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page