simple_ansible_controller MCP server
Commit Nov 8, 2026Lets an AI agent execute Ansible playbooks, manage inventories, and track task history through a minimal MCP or REST interface.
Also known as ppavlovrus/simple_ansible_controller, simple-ansible-controller
- Stars
- 0
- Tools
- 6
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 8, 2026
- License
- Apache-2.0
What is simple_ansible_controller MCP?
simple_ansible_controller lets an AI agent execute Ansible playbooks, manage inventories, and track task history through a minimal MCP or REST interface. It exposes 6 tools, such as run_playbook, syntax_check_playbook, get_task_status.
Summary generated from the project's README
About simple_ansible_controller MCP server
Executing Ansible playbooks and managing infrastructure through an AI agent is what this controller enables. It provides a lightweight execution engine designed specifically for machine-facing interfaces, avoiding the heavy resource requirements of large automation platforms. The system operates as a single process using a SQLite file for storage, making it easy to deploy via a container or a local installation.
Users can connect via a stdio transport for local use or through a REST API for remote access. When running as a container, an API key is required to authenticate requests. The server includes tools to run playbooks, check syntax, monitor task status, and retrieve logs. It also manages inventories through providers and allows for the storage and deletion of playbooks. This setup is ideal for developers who need a minimal, agent-shaped interface to drive infrastructure without the overhead of a full database or message broker fleet.
Written from the project's README. Every use case is checked against a quote from it.
simple_ansible_controller MCP tools 6
Detected from the READMErun_playbooksyntax_check_playbookget_task_statusget_task_logscancel_tasklist_tasks
| run_playbook | — | |
| syntax_check_playbook | — | |
| get_task_status | — | |
| get_task_logs | — | |
| cancel_task | — | |
| list_tasks | — |
Configuration
ANSIBLE_MCP_CONTAINER_RUNTIMEANSIBLE_MCP_DATA_DIRANSIBLE_MCP_EXECUTION_IMAGEANSIBLE_MCP_ISOLATION
| Name | Description | |
|---|---|---|
| ANSIBLE_MCP_CONTAINER_RUNTIME | — | |
| ANSIBLE_MCP_DATA_DIR | — | |
| ANSIBLE_MCP_EXECUTION_IMAGE | — | |
| ANSIBLE_MCP_ISOLATION | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableppavlovrus/simple_ansible_controller is public and reachablegithub.com/ppavlovrus/simple_ansible_controller ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/ppavlovrus/simple_ansible_controller ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model6 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubansible-mcp
A minimal Ansible controller with an MCP interface, for AI agents — and a REST API for the humans who work alongside them.
Give it a playbook and an inventory; it runs them and keeps the history, the logs and the artifacts of every run. One process, one SQLite file, one container. No database server, no message broker, no worker fleet.
Русская версия: README.ru.md
Why
Running Ansible against a handful of hosts is easy. Running it programmatically is not, and the moment you want that the options get heavy: AWX and Ansible Automation Platform need PostgreSQL, Redis, RabbitMQ, Receptor and in practice Kubernetes. For fifty hosts that control plane costs more than the problem it solves.
And an AI agent driving infrastructure needs a machine-facing interface. A REST API designed for a human clicking through a UI means deep object graphs and a dozen calls to launch one job; an agent wants a handful of well-named verbs.
That is what this is: a dumb executor with an agent-shaped interface. It does not write playbooks and does not decide what to run — the calling agent does both. See docs/concept.md.
Quick start
The three-line version is below; the user guide is the same path with every step explained, plus what to do when it does not work.
The fastest path is stdio, where the client launches the process. The package
is ansible-mcp-controller on PyPI, and ansible-core arrives with it:
uv tool install ansible-mcp-controller
ansible-mcp # speaks MCP on stdin/stdout
In Claude Code, or any MCP client:
{
"mcpServers": {
"ansible-mcp": {
"command": "uvx",
"args": ["--from", "ansible-mcp-controller", "ansible-mcp"],
"env": { "ANSIBLE_MCP_DATA_DIR": "/tmp/ansible-mcp" }
}
}
}
As a container, serving over HTTP:
docker build -f Containerfile -t ansible-mcp .
mkdir -p data && sudo chown 1000:1000 data # the image runs as uid 1000
docker run -p 8080:8080 -v ./data:/data \
-e ANSIBLE_MCP_API_KEY="$(openssl rand -hex 32)" ansible-mcp
The key is not optional there: the container listens beyond loopback, and the server refuses to serve an unauthenticated endpoint that executes playbooks. For a host installation, see packaging.
The tools
| Tool | What it does |
|---|---|
run_playbook |
Starts a run and returns a task id; the run continues in the background. check=true is a dry run: it contacts the hosts and changes nothing |
syntax_check_playbook |
Parses a playbook and says whether it is valid, contacting nothing |
get_task_status |
pending, running, success, failed or cancelled, with timestamps and exit code |
get_task_logs |
What Ansible printed, the tail by default, secrets removed; after_line pages forward without re-reading |
cancel_task |
Stops a queued or running playbook; needs confirm=true |
list_tasks |
Recent runs, newest first, filterable by status |
save_playbook / list_playbooks / get_playbook / delete_playbook |
Playbooks by name, so a run need not carry its text |
add_provider / list_providers / get_inventory / delete_provider |
Where an inventory comes from |
A provider is a small plugin that produces an inventory: static ships built in,
others register through the ansible_mcp.providers entry point group. Cloud
providers are the next ones planned.
The same thing with curl
When it serves HTTP, every one of those operations is also at /api/v1, on the
same port as /mcp and behind the same token:
curl -si -X POST http://127.0.0.1:8080/api/v1/runs \
-H "Authorization: Bearer $ANSIBLE_MCP_API_KEY" -H 'Content-Type: application/json' \
-d '{"playbook_name":"site","provider":"lab"}'
HTTP/1.1 202 Accepted
location: /api/v1/runs/8aeac1aeb682464c81b55b0a338e45ec
Then GET /api/v1/runs/{id} follows it and .../logs reads what it printed.
MCP stays the primary interface and REST is the second door onto the same
operations (ADR-0002, ADR-0015); the schema is at /api/v1/openapi.json, and
the user guide has
the whole loop.
What it deliberately does not do
- No RBAC, no multi-tenancy. One key gates the instance.
- No horizontal scaling. One node, concurrency bounded by a semaphore.
- No web UI.
- No playbook generation. That is the calling agent's job, and the LLM layer the prototype had was removed rather than ported.
Each of these is a decision with its reasoning and its rejected alternatives in the decision log. Outgrowing them is the signal to move to a full platform, and that boundary is what keeps this project small.
Security: the API key is shell access
Read this before exposing the endpoint to anything.
Whoever holds the API key can run arbitrary code on the controller host, as
the user the service runs as. Not through a bug — through the feature. A playbook
with hosts: localhost, or an inventory line carrying
ansible_connection=local, executes on the controller itself, and the controller
is built to run whatever playbook it is handed: it does not inspect, judge or
restrict them (ADR-0004).
So treat the key exactly as you would an SSH login to that host. One key covers the whole instance, there is no per-caller identity, and the audit log records what was done rather than by whom.
What reduces the blast radius today:
- Run it as an unprivileged user. The container image and the Debian package both do; a manual install should too.
- Give that user only the SSH credentials it needs, and no sudo on the controller.
- Keep the endpoint off the network unless it has to be on it. The stdio transport has no port at all, and a loopback bind needs no key because reaching it already means being on the machine.
What actually fixes it is running each playbook inside a container rather than on the host, and that now exists. It is off by default, because it needs a container runtime and this project promises none:
ANSIBLE_MCP_ISOLATION=true
ANSIBLE_MCP_CONTAINER_RUNTIME=podman
ANSIBLE_MCP_EXECUTION_IMAGE=my-execution-environment:latest
With it on, a playbook that says hosts: localhost runs inside a container and
the controller's filesystem is not there to touch. The operator turns it on for
the whole installation and a run may pick its image but cannot decline the
sandbox, which is what stops a caller stepping out of it
(ADR-0008,
ADR-0016). The
packaging notes have the
full setup; it is for the Debian package, not the container image, which already
isolates the whole service from its host.
What it does not change is the fleet: whoever holds the key can still run any playbook against every host the controller's credentials reach. Isolation bounds the damage on this machine, not on the machines it manages.
Working on it
poetry install
poetry run task tests # 250 tests
poetry run task lint # ruff + ruff format + mypy
make integration # playbooks against real hosts over SSH
poetry run task eval # can a local model actually drive this?
The eval harness is not decoration: it reads the tool schemas from the running server and measures whether a model picks the right tool. Several tool descriptions and the whole argument-coercion layer exist because it failed first. See evals/README.md.
Contributors, human or otherwise, start at AGENTS.md.
Documentation
| User guide | Install, connect, and everything it can do |
| Concept | The problem, the consumers, the trade-offs |
| Architecture | What the code does now |
| Configuration | Every setting |
| Reaching hosts | Keys, passwords and host keys, per install method |
| Decision log | Why the boundaries are where they are |
| Packaging | Container and Debian package |
| Evals | Measuring whether an agent can drive it |
| Integration | Connecting a client, and a ready-made skill |
| Roadmap | What is done and what is next (in Russian) |
Status
The core works: runs, cancellation, timeouts, recovery after a crash, playbook storage, providers, redaction, an audit trail, a checked token and both surfaces — MCP and REST. Not yet: cloud providers — see the roadmap.
License
Apache-2.0 — see LICENSE.
simple_ansible_controller MCP questions
What tools does simple_ansible_controller MCP provide?
It exposes 6 tools, including run_playbook, syntax_check_playbook, get_task_status, get_task_logs, cancel_task.
Does this server write playbooks for me?
No, the server is a dumb executor; the calling agent is responsible for writing the playbooks and deciding what to run.
Is there a web UI available?
No, the project deliberately does not include a web UI, focusing instead on MCP and REST interfaces.
Can I run playbooks in an isolated environment?
Yes, you can enable isolation to run playbooks inside a container rather than directly on the host.