MCP Ansible Server

How to use

To use the MCP server, first start the local Python MCP backend, then connect with your MCP client or editor plugin. The server runs through a standard Python process and respects your existing Ansible configuration, inventories, and project layout. You can list inventories, validate or run playbooks, scaffold roles, register and reuse projects, and perform ad hoc tasks, all via MCP tools that are exposed by the server.

Typical workflows include registering a project for reuse, discovering available playbooks under a project, and running a chosen playbook against the project’s inventory. You can also parse inventories, gather facts, ping hosts, validate YAML, manage galaxy dependencies, and bootstrap an entire project environment. All actions use your local Ansible setup and do not require any SSH access beyond what Ansible already uses.

How to install

# Prerequisites
# - Python 3.10+
# - macOS or Linux

# 1) Clone the MCP Ansible server repo
git clone https://github.com/bsahane/mcp-ansible.git
cd mcp-ansible

# 2) Create and activate a Python virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 3) Upgrade pip and install dependencies
python -m pip install -U pip
pip install -r requirements.txt

# 4) (Optional) install the project package in editable mode
pip install -e .

# 5) Run the MCP server
python src/ansible_mcp/server.py

Configuration and environment

Environment variables can customize how the MCP server discovers and runs Ansible projects. The server supports several MCP environment variables that you can set in your shell or in the client configuration to point to your project root, inventory, and project name.

{
  "mcpServers": {
    "ansible-mcp": {
      "command": "python",
      "args": [
        "/Users/bsahane/Developer/cursor/mcp-ansible/src/ansible_mcp/server.py"
      ],
      "env": {
        "MCP_ANSIBLE_PROJECT_ROOT": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server",
        "MCP_ANSIBLE_INVENTORY": "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini",
        "MCP_ANSIBLE_PROJECT_NAME": "projectAIOPS"
      }
    }
  }
}

You can also configure the same server in desktop tooling like Claude by duplicating the env setup shown above, pointing to your project root and inventory paths.

Environment variables overview

The following environment variables are supported for MCP Ansible usage. You can forward these to the running server process to customize behavior per project.

MCP_ANSIBLE_PROJECT_ROOT: absolute project root
MCP_ANSIBLE_INVENTORY: inventory path or directory
MCP_ANSIBLE_PROJECT_NAME: label for env project
MCP_ANSIBLE_ROLES_PATH: colon-separated roles paths
MCP_ANSIBLE_COLLECTIONS_PATHS: colon-separated collections paths
MCP_ANSIBLE_ENV_<KEY>: forwarded to process env (example: MCP_ANSIBLE_ENV_ANSIBLE_CONFIG)

Examples and practical usage

List hosts from a registered inventory, run a simple playbook, or run ad‑hoc tasks using the MCP client tools. You can register a project, discover playbooks, and execute them within the context of that project’s inventory and environment.

Notes

The server uses stdio transport. Do not print to stdout; logs go to stderr. Ansible connection and authentication follow your local Ansible configuration.

Troubleshooting and tips

If you encounter issues, verify that your virtual environment is activated, dependencies are installed, and the server script path is correct. Ensure that MCP_ANSIBLE_PROJECT_ROOT, MCP_ANSIBLE_INVENTORY, and MCP_ANSIBLE_PROJECT_NAME point to valid locations in your environment.

Security and best practices

Run the MCP server in a controlled environment and restrict access to configured endpoints. Leverage your existing Ansible security practices for inventories, vaults, and credentials, since the MCP server delegates to your Ansible configuration.

create-playbook

Create an Ansible playbook file from YAML string or object

validate-playbook

Syntax check a playbook

ansible-playbook

Run a playbook against hosts from inventory or localhost

ansible-task

Run an ad-hoc Ansible module task

ansible-role

Execute a role via a temporary generated playbook

create-role-structure

Scaffold a role directory tree

ansible-inventory

List hosts and groups from an inventory

register-project

Register an Ansible project for reuse

list-projects

Show registered projects and default project

project-playbooks

Discover playbooks under a project root

project-run-playbook

Run a playbook using a registered project's inventory/env

inventory-parse

Parse inventories with ansible.cfg awareness and merged vars

inventory-graph

Show inventory graph

inventory-find-host

Show a host’s groups and merged vars

ansible-ping

Ping hosts via ad-hoc module

ansible-gather-facts

Run setup and return facts

validate-yaml

Validate YAML files with error locations

galaxy-install

Install roles/collections from requirements

project-bootstrap

Bootstrap project including galaxy install and env inspection

inventory-diff

Diff two inventories

ansible-test-idempotence

Run playbook twice and verify idempotence on second run

galaxy-lock

Generate a lock file of installed roles/collections

vault-encrypt

Encrypt vault files (and related vault operations)