ansible-flow-mcp
Provides tools for searching Ansible module galleries, retrieving module schemas, and running Ansible modules and playbooks with optional check mode and security restrictions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ansible-flow-mcp Search for the apt module, get its schema, and run it in check mode to update all packages"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ansible-flow-mcp
Give agents Ansible. Not the keys.
This branch (CORE) is documentation only: why it exists, campaign screenshots, and the marketing site. The runnable MCP and hub live on DEVELOPMENT. main stays a product alias.
License | |
Install / code | |
Marketing site | |
Hub ops | |
Branches | |
Species | |
Voice |
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.
Related MCP server: AAP MCP Server
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.

Typical cases:
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.

Tool | Purpose |
| Gallery search |
| Slim argSpec for FQCN |
| Ad-hoc Ansible ( |
|
|
| Collections in gallery |
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.

Full mesh (withdrawn) | Hub/spoke (shipped) | |
Worker compromise | Could MCP-hop fleet-wide | No lateral MCP |
Inventory | Gossip / replicas | Hub is source of truth |
Agent attach | Any node | Hub only |
Ops model | Mesh OS | Classic Ansible bastion |
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_collectionsLab one-shot
cd lab && ./scripts/demo.sh
# then: ./scripts/tui.sh | ./scripts/opencode-host.shSee lab/README.md.
Quick start
Full guide (all paths, verify, troubleshooting): docs/QUICKSTART.md
Path | Guide section |
Local MCP + Cursor/Claude | |
Compose lab (hub + 3 spokes) | |
Bare-metal hub/spoke |
Single-node / dev (short form)
Requirements: Python ≥ 3.11 · collection ansible.posix (JSON callback) · collections you will run.pip install pulls ansible-core (provides ansible / ansible-playbook).
cd ansible-flow-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
ansible-galaxy collection install ansible.posix
pytest -q
ansible-flow-mcpOr install via pypi.org
pip install ansible-flow-mcp
ansible-galaxy collection install ansible.posix
ansible-flow-mcpEditor 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)
Control | Behavior |
Collection allowlist | Only configured collections |
Module deny list |
|
Check mode | Default true on |
Playbook jail | Allowlisted roots · size limit · |
No shell interpolation | argv-only subprocess |
Hub inventory | Enrolled hosts only · no client |
Spoke path | SSH ForceCommand · localhost exec · no peer fabric |
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 modulescatalog/gallery.json+catalog/schemas/: searchable galleryRegenerate:
python scripts/generate_catalog.pyGalaxy factory TUI: scripts/factory/README.md
OpenFlow reads this gallery for its Ansible canvas (plan · umbrella).
OpenFlow | This MCP server |
Palette Ansible gallery |
|
Form | JSON module options |
|
Playbook resource |
|
Control-node SSH / become | Inventory + Ansible config · hub→spoke SSH in hub mode |
Env (common)
Variable | Meaning |
| Override catalog path |
| Comma-separated allowlist override |
| Default |
| Seconds (default 120 module / 300 playbook) |
| Extra playbook roots ( |
| Hub state (default: |
| Spoke state (same pattern under |
License & publish
Apache-2.0
pip install build twine && python -m build
# twine upload dist/*uvx --from ansible-flow-mcp ansible-flow-mcpFamily
Written standard: private TheFLOW.
OpenFlow: reads this Ansible gallery
mcp-flow: MCP gateway
skill-flow: Agent Skills
wiki-flow, roster-flow, CleanFlow, ProjectEverflow: siblings
Available Tools
5 toolsget_module_schemaA
Return slim arg schema for a module FQCN (when catalog has it).
Inputs: module (required). Returns: result
list_collectionsA
List collections present in the committed gallery.
Inputs: no named parameters. Returns: result
run_moduleB
Run an Ansible module via local ansible CLI. Prefer check_mode=true first.
Inputs: module (required), args, hosts, become, +5 more. Returns: result
run_playbookA
Run ansible-playbook on a path under allowlisted roots. Prefer check_mode=true first.
Inputs: playbook (required), tags, limit, become, +7 more. Returns: result
search_modulesA
Search allowlisted Ansible modules (gallery) by name, FQCN, collection, or description.
Inputs: limit, query. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct action: searching the module catalog, retrieving module schemas, running a module, running a playbook, and listing collections. There is no functional overlap between any of the tools, making selection unambiguous.
All tool names follow a consistent verb_noun pattern using snake_case: search_modules, get_module_schema, run_module, run_playbook, list_collections. The naming is predictable and uniform across the entire set.
With 5 tools, the set is well-scoped for an Ansible flow server. It covers the essential operations of discovering, inspecting, and executing Ansible content without unnecessary bloat or heaviness.
The toolset covers the core lifecycle: discover (search/list), inspect (get schema), and execute (run module/playbook). A minor gap is the lack of a direct way to list playbooks or manage inventory, but these are not essential for the stated flow-centric purpose.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Related MCP Servers
- AlicenseCqualityFmaintenanceThis Model Context Protocol server enables AI assistants to interact directly with Ansible, allowing them to execute playbooks, manage inventory, check syntax, and perform other Ansible operations.1827MIT
- AlicenseBqualityDmaintenanceEnterprise-grade MCP server exposing Ansible Automation Platform 2.x as a complete AI interface for LLMs, enabling natural language management of automation resources.861Apache 2.0
- FlicenseAqualityDmaintenanceAn MCP server that lets AI agents discover Ansible Galaxy collection input/output contracts, including module arguments, return values, and role facts, to help generate accurate playbooks.6-
- FlicenseNot gradedqualityDmaintenanceIndustry-standard MCP server for AWX/AAP/Ansible Tower automation, enabling AI agents to manage job templates, launch and monitor jobs, and handle inventories and projects through natural language.14-