ansible-flow-mcp

Give agents Ansible. Not the keys.

MCP server that exposes real Ansible modules and playbooks to AI agents — and a SSH hub/spoke fabric so multi-host automation is enrolled, bastion-scoped, and check-first by default.

OpenFlow dual-track · Campaign storyboard · Hub/spoke ops · Apache-2.0

Not affiliated with Red Hat or the Ansible project beyond using the public Ansible CLI and docs.

New here? Full step-by-step: docs/QUICKSTART.md — local MCP · compose lab · bare-metal hub/spoke · editor wiring.

Visual tour

Why it exists	Agent loop
Hub / spoke fabric	Operators

Screenshots live in docs/images/campaign-*.png. Re-shoot from docs/campaign/ with ./capture.sh.

Why this exists

Agents on a god-mode control node invent inventory, reach for shell, and treat every worker as an entrypoint. That is not a security model.

You need this when:

• You want Cursor / Claude / OpenCode to run Ansible like an operator, not freestyle root across the fleet
• Multi-host must mean bastion ops you already understand (SSH, inventory, enrollment) — not a mesh hop plane
• Prompt injection will still ask for bad ops — policy and topology must refuse

Two tracks

1. Agent loop — search → schema → check → execute

Curated module gallery. Slim argSpec before any run. Check mode default. Free-form modules denied. Playbooks path-jailed.

Ritual (modules): search_modules → get_module_schema → run_module(..., check_mode=true) → apply only if appropriate.

Ritual (playbooks): confirm path under allowlisted roots → check → apply.

2. Hub/spoke — nothing is a target until enrolled

Secure multi-host mode: agent attaches to the hub only. Hub reaches spokes over SSH only. Spokes execute localhost and cannot lateral-move via this fabric.

Enrollment: hub init → issue-token (TTL, one-time jti) → spoke join (token + SSH identity) → hub inventory. Runtime: ForceCommand MCP session — no shell on the hub→spoke path.

Hub tools: list_nodes / hub_status, issue_token, revoke_node, groups (create_group, set_group_members, …), spoke_call, plus catalog run_* against enrolled hosts or groups only. Client-supplied -i is rejected in hub mode.

Deep ops: docs/HUB.md.

Operators

Day-2 surface matches the agent: enroll, group, hand the hub to OpenCode.

ansible-flow-mcp hub init --name ctrl-01
ansible-flow-mcp hub issue-token --name web-03 --ttl 15m
ansible-flow-mcp spoke join --token "$TOKEN" --hub user@hub:22 --public-addr web-03.example.com
ansible-flow-mcp hub session          # MCP stdio for the agent
ansible-flow-mcp tui                  # servers · groups · invite · OpenCode
ansible-flow-mcp hub spoke-call --node web-03 --tool list_collections

Lab one-shot

cd lab && ./scripts/demo.sh
# then: ./scripts/tui.sh  |  ./scripts/opencode-host.sh

See lab/README.md.

Quick start

Full guide (all paths, verify, troubleshooting): docs/QUICKSTART.md

Single-node / dev (short form)

Requirements: Python ≥ 3.11 · ansible-core on PATH · collection ansible.posix · collections you will run.

python3 -m pip install --user 'ansible-core>=2.16,<2.19'
export PATH="$HOME/.local/bin:$PATH"
ansible-galaxy collection install ansible.posix

cd ansible-flow-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
ansible-flow-mcp

Editor snippets: examples/cursor-mcp.json, examples/claude-desktop.json.
Hub + OpenCode: examples/opencode-hub.jsonc · ansible-flow-mcp hub write-opencode-config.

{
  "mcpServers": {
    "ansible-flow": {
      "command": "/path/to/ansible-flow-mcp/.venv/bin/ansible-flow-mcp"
    }
  }
}

Security (honest)

Residual: hub compromise = fleet (same class as any Ansible control node). Harden the bastion — see docs/SECURITY.md and docs/HUB.md.

Catalog & OpenFlow

• catalog/collections-allowlist.yml — allowlist + deny free-form modules
• catalog/gallery.json + catalog/schemas/ — searchable gallery
• Regenerate: python scripts/generate_catalog.py
• Galaxy factory TUI: scripts/factory/README.md

Dual-tracked with OpenFlow Ansible canvas gallery
(plan · umbrella).

Env (common)

License & publish

Apache-2.0

pip install build twine && python -m build
# twine upload dist/*

uvx --from ansible-flow-mcp ansible-flow-mcp