Ansible NLP MCP

Local MCP server to allow Codex to interact with this Ansible repository through natural language, using safe tools instead of exposing a generic shell.

Tools

• health: shows root, timeout, and whether mutable execution is enabled.

• list_playbooks: lists executable playbooks and workflows.

• inspect_playbook: summarizes plays, hosts, vars_files, initial tasks, and common required variables.

• suggest_playbooks: ranks playbooks based on a natural language request.

• inventory_graph: runs ansible-inventory --graph.

• inventory_summary: summarizes inventory groups and hosts.

• syntax_check: runs ansible-playbook --syntax-check.

• check_playbook: runs ansible-playbook --check.

• run_playbook: runs the actual playbook, blocked by default.

• ping_hosts: runs ansible -m ping or ansible.windows.win_ping.

• list_logs and tail_log: queries logs inside logs/.

Related MCP server: AAP MCP Server

Installation

cd /root/ansible
python3 -m venv .venv-mcp
. .venv-mcp/bin/activate
pip install -r ansible_mcp/requirements.txt

Local testing

cd /root/ansible
. .venv-mcp/bin/activate
python -m ansible_mcp.server

This command starts an MCP server over stdio and waits for an MCP client.

Codex configuration

Example for .codex/config.toml in the project, or for ~/.codex/config.toml if you want to enable it globally:

[mcp_servers.ansible]
command = "/root/ansible/.venv-mcp/bin/python"
args = ["/root/ansible/ansible_mcp/server.py"]
cwd = "/root/ansible"
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 900
env = { ANSIBLE_MCP_ROOT = "/root/ansible", ANSIBLE_MCP_ALLOW_RUN = "0" }

With ANSIBLE_MCP_ALLOW_RUN = "0", the MCP allows inspection, inventory, ping, syntax-check, and check mode, but blocks actual playbook execution.

To allow mutable execution:

[mcp_servers.ansible]
command = "/root/ansible/.venv-mcp/bin/python"
args = ["/root/ansible/ansible_mcp/server.py"]
cwd = "/root/ansible"
enabled = true
startup_timeout_sec = 10
tool_timeout_sec = 900
env = { ANSIBLE_MCP_ROOT = "/root/ansible", ANSIBLE_MCP_ALLOW_RUN = "1" }

Even when enabled, run_playbook still requires confirm = "RUN" in the tool call.

NLP intent examples

• "Which playbook do I use to update Windows on wuday1?"

• "Run syntax-check on the Windows Update playbook with day=wuday1."

• "Run the Linux update in check mode only on the rocky group."

• "Show the latest Citrix Day logs."

• "List the inventory groups and how many hosts are in each one."