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

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/

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.