ansible-flow-mcp

MCP server that exposes Ansible modules and playbooks to AI agents:

search → schema → check → execute

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

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

Requirements

• Python ≥ 3.11

• ansible / ansible-core on PATH for real runs (unit tests mock the CLI)

• Collection ansible.posix (JSON stdout callback ansible.posix.json on ansible-core ≥ 2.15)

• Other collections you intend to use installed on the control node

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

Related MCP server: MCP SysOperator

Install (dev)

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

Run (stdio MCP)

ansible-flow-mcp
# or: python -m ansible_flow_mcp.server

Cursor / Claude Desktop

See examples/cursor-mcp.json and examples/claude-desktop.json.

Local path example:

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

Tools

Agent ritual (modules)

1. search_modules

2. get_module_schema

3. run_module(..., check_mode=true)

4. run_module(..., check_mode=false) if appropriate

Agent ritual (playbooks)

1. Confirm playbook path is under an allowlisted root

2. run_playbook(..., check_mode=true)

3. run_playbook(..., check_mode=false) if appropriate

Catalog

• catalog/collections-allowlist.yml — allowed collections + denied free-form modules

• catalog/gallery.json — searchable module list

• catalog/schemas/*.json — optional UI/agent schemas (full gallery coverage)

Regenerate when ansible-doc is available:

pip install pyyaml
python scripts/generate_catalog.py

Env

Default playbook roots include cwd, ./playbooks, ./ansible, /data/ansible, and the system temp dir. Max playbook size 2MB; .yml / .yaml only.

Security

See docs/SECURITY.md. Free-form modules (command/shell/raw/script) are denied by default. Playbooks are path-jailed. CLI is argv-only (no shell interpolation). Structured output uses ansible.posix.json.

OpenFlow parity

Golden runner fixtures under tests/fixtures/ define the shared result shape for OpenFlow’s openflow-node-base.ansible executor (TypeScript port).

OpenFlow docs: docs/ansible.md

License

Apache-2.0

Publish (PyPI)

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

Or from git:

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

Schemas cover the full committed gallery (builtin + popular collections). Regenerate with scripts/generate_catalog.py when ansible-doc is available.