ansible-mcp

# @yawlabs/ansible-mcp

[![Add to Yaw MCP](https://yaw.sh/yaw-mcp-button.svg)](https://yaw.sh/mcp/install?name=Ansible&command=npx&args=-y%2C%40yawlabs%2Fansible-mcp&description=Ansible%20checkout%20truth%3A%20module%20specs%2C%20task%20args%2C%20roles%2C%20inventory%2C%20plays%2C%20upgrade%20impact&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fansible-mcp)

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

**What is actually true in THIS Ansible checkout on THIS control node: the exact option specs of the modules you have INSTALLED (so coding agents stop writing options that do not exist in your collection version), task-argument checks, role interfaces, inventory structure and vars (redacted), play structure, effective config, requirements drift, and what a collection upgrade would break in your tasks.** It is read-only: it never runs a play, never runs `--check`, never connects to a managed host and never supplies a vault secret. It complements Red Hat's servers rather than replacing them: AAP MCP answers what is true in the controller, ADT MCP takes actions (lint `--fix`, navigator runs, scaffolding, EE builds). Run them together.

[![npm version](https://img.shields.io/npm/v/@yawlabs/ansible-mcp)](https://www.npmjs.com/package/@yawlabs/ansible-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

Built and maintained by [Yaw Labs](https://yaw.sh).

## Why this one?

Your checkout has `community.general 9.5.2`; the model's training data has whatever version it saw most. Agents then write `git_config: list_all: true` (removed in 11.0.0), forget `name` (required since 12.0.0), or set `state: present` on `rhsm_repository` (no longer accepted). The VS Code language server knows the exact specs, but only a person in the editor sees them. This server lets the agent check *before* it writes, against what is installed.

- **Installed, not latest** -- the source of truth is `ansible-doc --json` run against your collections paths, with redirects (`ufw` -> `community.general.ufw`) and tombstones resolved.
- **Checks what lint skips** -- `ansible-lint`'s `args` rule skips modules with action plugins (`copy`, `template`); `ansible_check_task_args` catches their unknown options and bad values, and says plainly which cross-option rules ansible-doc cannot express.
- **YAML 1.1 aware** -- Ansible parses YAML 1.1, so unquoted `off` is `false` and `0755` is the integer 493. The server reads YAML the same way and says when that is probably a bug.
- **Read-only by construction** -- configured vault password scripts never run (a server-owned dummy password file replaces them), script and plugin inventory sources are off by default, and play-level lookups are refused before Ansible parses a playbook.
- **Collection upgrade impact** -- downloads only the target version into its own cache and diffs the arg specs of the modules your tasks actually use, tied to file:line.
- **macOS, Linux, and Windows through WSL** -- Ansible has no Windows control node; on Windows the server spawns it through `wsl.exe --exec` (no shell anywhere).

## Tools

| Tool | What it does |
|---|---|
| `ansible_project_info` | ansible-core version, effective config file, collections and roles paths, installed `ansible-*` binaries, detected playbooks, inventories (with whole-file vault count), roles and requirements files. Call this first. |
| `ansible_module_doc` | Every option of one module or plugin as installed: type, required, default, choices, aliases, suboptions, deprecations, `no_log`, the providing collection version, `[has action plugin]`, returns and (optionally) examples. |
| `ansible_module_search` | Find installed modules/plugins by name or description, ranked exact, prefix, token, then description. |
| `ansible_check_task_args` | Check inline task YAML or a tasks file / playbook against the installed docs: unknown options, missing required ones (aliases count), bad choices and types, suboptions, `mode: 0755`, deprecated options, duplicate keys. Never claims "valid": it names what ansible-doc cannot check. |
| `ansible_role_interface` | A role's argument_specs entry points and options, defaults (redacted, `no_log` honoured), undocumented defaults, dependencies, vars names, galaxy_info. Local roles and `ns.collection.role`. |
| `ansible_inventory` | Groups, hosts, and inventory-level vars (names or values), always redacted. Whole-file vaults degrade to a per-file view instead of failing. |
| `ansible_playbook_structure` | `--syntax-check`, then plays, matched hosts, tasks with module and file:line, tags, and the deprecation warnings Ansible printed while parsing. |
| `ansible_config` | Effective config with origins (ansible.cfg, env, default); galaxy credentials always redacted; settings the server overrides for safety are flagged. |
| `ansible_collections` | requirements.yml vs installed: ok / VIOLATES / MISSING with file:line, galaxy constraint semantics, and shadowed copies across collections paths. |
| `ansible_lint_summary` | `ansible-lint --offline` grouped by rule with counts, severities and locations. Never fixes. |
| `ansible_upgrade_impact` | What breaks in this project's tasks if a collection moves to an exact version: removed/moved modules (runtime.yml redirects and tombstones), removed options and aliases, newly required options, dropped choices, type and default changes, requirements constraints, `requires_ansible`, an optional syntax-check against the target, and a verdict. |

Every tool takes an optional `dir` (the project). Tool names carry an `ansible_` prefix and never reuse ADT MCP's names (`ansible_lint`, `ansible_navigator`, ...), so both can sit behind one aggregator.

### Division of authority

| Question | Authority |
|---|---|
| Controller jobs, job templates, controller inventories, RBAC | AAP MCP |
| Scaffold content, `ansible-lint --fix`, run via ansible-navigator, set up a venv or EE | ADT MCP |
| Interactive editing for a person | VS Code Ansible extension (language server) |
| Generate new content from intent | Ansible Lightspeed |
| Execute modules against hosts | not this server |
| Installed specs, task-argument validity, role interfaces, local inventory, play structure, effective config, dependency drift, collection upgrade impact | **ansible-mcp** (read-only) |

### What is read-only, and what touches the network

- **Never run:** plays, modules, `--check`, `--diff`, fact gathering. The only Ansible commands are `ansible --version`, `ansible-config dump`, `ansible-doc`, `ansible-inventory --list/--host/--graph`, `ansible-playbook --syntax-check/--list-*`, `ansible-galaxy collection list` / `role list`, `ansible-lint --offline`, and (only in `ansible_upgrade_impact`) `ansible-galaxy collection install --no-deps -p <server cache>`.
- **Never written:** your project, your collections and roles paths, requirements files, and anything inside an existing `~/.ansible`. Ansible's local temp, galaxy cache and (when you have none) galaxy token file are redirected to the server's cache. The one residue: Ansible creates an empty `~/.ansible` when it does not exist, and ansible-lint creates empty `~/.ansible/roles` / `~/.ansible/collections` when they are missing.
- **Vault:** no secret is ever supplied, and a `vault_password_file` / `vault_identity_list` script named in ansible.cfg never runs (it is replaced by a server-owned file holding a random password). Inline `!vault` values print as `<vaulted>`; whole-file vaults are listed, not read.
- **Dynamic inventory** (script, constructed, cloud plugins) runs code and calls APIs, so it is off unless `ANSIBLE_MCP_ALLOW_DYNAMIC_INVENTORY=1`; skipped sources are named in the answer.
- **Residual risk, stated:** `ansible-playbook --syntax-check` (and ansible-lint, which runs it) evaluates Jinja in play-level `name`, `hosts` and `vars_files` and imports playbook-adjacent `vars_plugins/`. Treat `dir` as code you would run `--syntax-check` on. Lookups in those fields are refused before Ansible sees them unless `ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS=1`, and local plugin files are listed in the answer.
- **Redaction** (`ansible_inventory`, `ansible_role_interface`, `ansible_config`, lint messages): vault markers, plus any string equal to a hidden one, plus values under secret-like names (`ansible_become_password`, `api_token`, `vault_db_password`, ... but not `vault_addr` or `private_key_file`), plus secret-shaped strings (private keys, JWTs, GitHub/GitLab/Slack/npm tokens; URL passwords masked in place). Galaxy server tokens and passwords are always redacted. There is no "show secrets" switch.
- **Network:** only `ansible_upgrade_impact`, on a cache miss, to Galaxy or the servers in your ansible.cfg (`openWorldHint: true`). The cache is never evicted automatically; deleting it is safe.

Example `ansible_check_task_args` output (real docs, community.general 9.5.2):

```
playbooks/tasks/bad_args.yml: 7 tasks checked against installed docs (ansible-core 2.21.5): 5 problems in 3 tasks
  :3 ansible.builtin.copy [has action plugin; ansible-lint skips its arguments]
    unknown option owner_name (line 7)
    unknown option state (line 9)
    backup (line 8): expected bool, got a string that is not a boolean ('maybe')
  :12 ansible.posix.mount
    missing required option path (aliases: name)
  :18 ansible.builtin.file (key=value form): ok (dest is an alias of path)
  :21 ansible.builtin.copy: ok by docs [not checked: src and content are mutually exclusive in the module's argument_spec, which ansible-doc does not expose]
  :32 ansible.builtin.apt: ok; 2 templated values not checked (state, update_cache)
  :38 community.general.ufw (from short name ufw)
    proto (line 41): 'tcpx' is not one of any|tcp|udp|ipv6|esp|ah|gre|igmp
```

Example `ansible_upgrade_impact` output (real 9.5.2 -> 12.0.0 docs):

```
upgrade community.general 9.5.2 -> 12.0.0 (major) for /work/site