# Ansible MCP Server

> Ansible MCP Server is an open-source MCP server for developer tools. Read-only Ansible checks for agents: installed module specs, task args, upgrade impact. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows, self-hosted
- **Website:** https://yaw.sh/mcp-servers/ansible-mcp/
- **Repository:** https://github.com/yawlabs/ansible-mcp
- **MCP Registry name:** io.github.YawLabs/ansible-mcp
- **Categories:** developer tools, cloud and infrastructure
- **Listing updated:** 2026-11-15

## About

Agents often write Ansible tasks from training data that predates the collection version you actually have installed. This server answers from your own checkout instead, using ansible-doc --json against your collections paths, so an option removed in a newer community.general release is flagged before the task is written.

It is read-only by design. The README says it never runs a play or --check, never connects to a managed host and never supplies a vault secret; vault password scripts are replaced with a dummy file and script or plugin inventory sources are off by default. Inventory output is redacted.

It also parses YAML the way Ansible does (YAML 1.1), so unquoted off becomes false and 0755 becomes 493, and it warns when that is probably a bug. A collection-upgrade check downloads only the target version into its own cache and diffs the argument specs of modules your tasks use, ending in a verdict tied to file and line. On Windows it runs Ansible through WSL.

## Features

- **Installed-version specs:** Returns every option of a module as installed, including choices, aliases and deprecations.
- **Task argument checks:** Flags unknown, missing or badly typed options in inline YAML or a tasks file.
- **Role interfaces:** Reads argument specs, defaults, dependencies and galaxy_info from a role.
- **Upgrade impact:** Diffs the argument specs your tasks use against a target collection version.
- **YAML 1.1 awareness:** Reads unquoted values the way Ansible does and warns about likely mistakes.
- **Read-only guarantees:** Never runs plays, contacts managed hosts or uses vault secrets.

## Good for

- Check an agent-written task against the modules installed in your checkout
- See what bumping community.general would break in existing tasks
- Review a role's inputs and defaults before reusing it
- Audit inventory and play structure without exposing secrets

## Install

### Claude Code (Terminal)

```sh
claude mcp add ansible-mcp -- npx -y @yawlabs/ansible-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "ansible-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@yawlabs/ansible-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "ansible-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@yawlabs/ansible-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "ansible-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@yawlabs/ansible-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "ansible-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@yawlabs/ansible-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "ansible-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@yawlabs/ansible-mcp"
      ]
    }
  }
}
```

## Tools

- `ansible_project_info`: Reports ansible-core version, effective config, collections and roles paths, playbooks, inventories and requirements files.
- `ansible_module_doc`: Returns every option of one module or plugin as installed, with types, choices, aliases, deprecations and collection version.
- `ansible_module_search`: Finds installed modules and plugins by name or description.
- `ansible_check_task_args`: Checks inline task YAML or a tasks file against installed docs for unknown, missing or invalid options.
- `ansible_role_interface`: Reads a role's argument-spec entry points, options, defaults, dependencies and galaxy_info.
- `ansible_upgrade_impact`: Diffs argument specs of modules your tasks use against a target collection version.

## FAQ

### Does it run my playbooks?

No. It is read-only and never runs a play, never runs --check and never connects to a managed host.

### Where do the module specs come from?

From ansible-doc --json run against the collections paths in your checkout, not from upstream docs.

### Does it work on Windows?

Yes through WSL, because Ansible has no Windows control node; the server starts it with wsl.exe --exec.

### What licence is it under?

MIT, published on npm as @yawlabs/ansible-mcp.

### Is Ansible MCP Server free?

Yes. Ansible MCP Server is open source, so you can use and self-host it for free.

### How do I add Ansible MCP Server to Claude Code?

Run this command in your terminal: claude mcp add ansible-mcp -- npx -y @yawlabs/ansible-mcp

### What are the best alternatives to Ansible MCP Server?

The closest alternatives to Ansible MCP Server are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/ansible-mcp-server
