Ansible MCP Server

@yawlabs/ansible-mcp

单击即可将其添加到本地 Yaw MCP 配置中，以便在每次 Yaw Terminal 会话中使用。也可以在下方手动安装。

**了解当前 Ansible 检出版本在当前控制节点上的实际情况：已安装模块的精确选项规范（让编码 Agent 不再编写当前集合版本中不存在的选项）、任务参数检查、角色接口、清单结构和变量（已脱敏）、Play 结构、有效配置、requirements 漂移，以及升级集合会对任务造成哪些影响。**它是只读的：绝不会运行 Play、运行 --check、连接受管主机或提供 vault 密钥。它与 Red Hat 的服务互为补充，而非替代：AAP MCP 解答控制器中的实际情况，ADT MCP 执行操作（lint --fix、navigator 运行、脚手架搭建、EE 构建）。可以同时运行。

由 Yaw Labs 构建并维护。

为什么选择它？

你的检出版本使用 community.general 9.5.2；模型的训练数据则来自它见过的某个版本。于是 Agent 会写出 git_config: list_all: true（该选项已在 11.0.0 中移除）、忘记 name（自 12.0.0 起为必需），或在 rhsm_repository 上设置 state: present（已不再接受）。VS Code 语言服务器知道精确的规范，但只有编辑器中的人才能看到。本服务让 Agent 在写入之前，根据已安装的内容进行检查。

• 检查已安装版本，而非最新版本——事实依据是针对你的集合路径运行 ansible-doc --json 的结果，并解析重定向（ufw -> community.general.ufw）和墓碑。
• 检查 lint 会跳过的内容——ansible-lint 的 args 规则会跳过带有 action 插件的模块（copy、template）；ansible_check_task_args 会捕获这些模块中的未知选项和无效值，并明确说明哪些跨选项规则无法通过 ansible-doc 表达。
• 支持 YAML 1.1——Ansible 解析 YAML 1.1，因此未加引号的 off 会变成 false，而 0755 会变成整数 493。本服务以相同方式读取 YAML，并指出可能存在的错误。
• 从设计上确保只读——配置的 vault 密码脚本绝不会运行（由服务端管理的虚拟密码文件会取代它们）；脚本和插件清单源默认关闭；在 Ansible 解析 Playbook 之前，会拒绝 Play 级别的查找操作（无法通过预扫描完整读取的任何 Playbook 或 lint 目标也一样）。
• 分析集合升级影响——仅将目标版本下载到独立缓存，并对任务实际使用的模块参数规范进行差异比较，同时标明文件和行号。
• 支持 macOS、Linux 和通过 WSL 运行的 Windows——Ansible 没有 Windows 控制节点；在 Windows 上，本服务通过 wsl.exe --exec 启动 Ansible（全程不使用 shell）。

工具

工具	功能
ansible_project_info	ansible-core 版本、有效配置文件、集合和角色路径、已安装的 ansible-* 二进制文件、检测到的 playbook、清单（含整个文件的 vault 数量）、角色和 requirements 文件。请先调用此工具。
ansible_module_doc	已安装的某个模块或插件的所有选项：类型、必填项、默认值、可选值、别名、子选项、弃用信息、提供该模块或插件的集合版本、[has action plugin]、返回值，以及（可选）示例。
ansible_module_search	按名称或描述查找已安装的模块/插件，并按完全匹配、前缀匹配、词元匹配、描述匹配的顺序排序。
ansible_check_task_args	根据已安装的文档检查内联任务 YAML 或任务文件/playbook：未知选项、缺少必填项（别名也计入）、无效的可选值和类型、子选项、mode: 0755、已弃用选项、重复键。绝不会声称“有效”：会指出 ansible-doc 无法检查的内容。
ansible_role_interface	角色的 argument_specs 入口和选项、默认值（已脱敏，并遵循 no_log）、未记录的默认值、依赖项、变量名称、galaxy_info。适用于本地角色和 ns.collection.role。
ansible_inventory	组、主机和清单级变量（名称或值），始终脱敏。对于整个文件都经过 vault 加密的情况，会改为提供逐文件视图，而不会失败。
ansible_playbook_structure	先执行 --syntax-check，然后列出 play、匹配的主机、含模块名称和 file:line 的任务、标签，以及 Ansible 解析时输出的弃用警告。
ansible_config	显示带来源（ansible.cfg、环境变量、默认值）的有效配置；galaxy 凭据始终脱敏；标记服务出于安全考虑覆盖的设置。
ansible_collections	对比 requirements.yml 与已安装集合：显示 ok / VIOLATES / MISSING 及 file:line、Galaxy 约束语义，以及集合路径中被遮蔽的副本。
ansible_lint_summary	按规则汇总 ansible-lint --offline 结果，包括计数、严重级别和位置。不会修复问题。
ansible_upgrade_impact	如果集合升级到指定的精确版本，项目中的任务会有哪些变化：已移除/迁移的模块（runtime.yml 重定向和 tombstone）、已移除的选项和别名、新增的必填选项、已删去的可选值、类型和默认值变更、requirements 约束、requires_ansible、可选的目标版本语法检查，以及结论。

每个工具都接受一个可选的 dir（项目目录）。工具名称带有 ansible_ 前缀，且不会重复使用 ADT MCP 的名称（ansible_lint、ansible_navigator 等），因此两者可以同时接入同一个聚合器。

权限划分

问题	权限方
控制器任务、任务模板、控制器清单、RBAC	AAP MCP
脚手架内容、ansible-lint --fix、通过 ansible-navigator 运行、设置 venv 或 EE	ADT MCP
供人员交互式编辑	VS Code Ansible 扩展（语言服务器）
根据意图生成新内容	Ansible Lightspeed
对主机执行模块	非本服务提供
已安装的规范、任务参数有效性、角色接口、本地清单、play 结构、有效配置、依赖项漂移、集合升级影响	ansible-mcp（只读）

什么是只读操作，哪些操作会访问网络

• 绝不运行： play、module、--check、--diff、事实收集。唯一允许的 Ansible 命令是 ansible --version、ansible-config dump、ansible-doc、ansible-inventory --list/--host/--graph、ansible-playbook --syntax-check/--list-*、ansible-galaxy collection list / role list、ansible-lint --offline，以及（仅在 ansible_upgrade_impact 中）ansible-galaxy collection install --no-deps -p <server cache>。
• **绝不写入：**你的项目、你的 collections 和 roles 路径、requirements 文件，以及现有 ~/.ansible 中的任何内容。Ansible 的本地临时目录、Galaxy 缓存和（如果你没有）Galaxy token 文件都会重定向到服务的缓存。唯一残留：如果 ~/.ansible 不存在，Ansible 会创建一个空的 ~/.ansible；如果 ~/.ansible/roles / ~/.ansible/collections 不存在，ansible-lint 会创建空目录。
• **Vault：**绝不会提供任何密钥，ansible.cfg 中指定的 vault_password_file / vault_identity_list 脚本也不会运行（会由服务管理的文件替代，其中存放随机密码）。内联 !vault 值会显示为 <vaulted>；整文件加密的 Vault 文件只会列出，不会读取。
• 动态 inventory（脚本、构造型、云插件）会运行代码并调用 API，因此默认关闭，除非设置 ANSIBLE_MCP_ALLOW_DYNAMIC_INVENTORY=1；答案中会列出被跳过的来源。
• 明确说明的残余风险：ansible-playbook --syntax-check（以及会运行它的 ansible-lint）会求值 play 级别 name、hosts 和 vars_files 中的 Jinja，并导入与 playbook 相邻的 vars_plugins/。请将 dir 视为你会对其运行 --syntax-check 的代码。除非设置 ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS=1，否则这些字段中的查找操作会在 Ansible 看到之前被拒绝；答案中会列出本地插件文件。
• 脱敏（ansible_inventory、ansible_role_interface、ansible_config、lint 消息）：Vault 标记、任何与隐藏值相同的字符串、类似机密名称下的值（ansible_become_password、api_token、vault_db_password 等，但不包括 vault_addr 或 private_key_file），以及类似机密的字符串（私钥、JWT、GitHub/GitLab/Slack/npm token；URL 密码会就地屏蔽）。Galaxy 服务 token 和密码始终会脱敏。没有“显示机密”的开关。
• **网络：**仅 ansible_upgrade_impact 会在缓存未命中时访问 Galaxy 或 ansible.cfg 中的服务器（openWorldHint: true）。缓存不会自动清除；删除缓存是安全的。

ansible_check_task_args 输出示例（真实文档，community.general 9.5.2）：

playbooks/tasks/bad_args.yml: 7 tasks checked against installed docs (ansible-core 2.21.5): 5 problems in 3 tasks
  :3 ansible.builtin.copy [has action plugin; ansible-lint skips its arguments]
    unknown option owner_name (line 7)
    unknown option state (line 9)
    backup (line 8): expected bool, got a string that is not a boolean ('maybe')
  :12 ansible.posix.mount
    missing required option path (aliases: name)
  :18 ansible.builtin.file (key=value form): ok (dest is an alias of path)
  :21 ansible.builtin.copy: ok by docs [not checked: src and content are mutually exclusive in the module's argument_spec, which ansible-doc does not expose]
  :32 ansible.builtin.apt: ok; 2 templated values not checked (state, update_cache)
  :38 community.general.ufw (from short name ufw)
    proto (line 41): 'tcpx' is not one of any|tcp|udp|ipv6|esp|ah|gre|igmp

ansible_upgrade_impact 输出示例（真实的 9.5.2 -> 12.0.0 文档）：

upgrade community.general 9.5.2 -> 12.0.0 (major) for /work/site
target: requires_ansible '>=2.17.0' ok (ansible-core 2.21.5); dependencies: none; downloaded (cache: ...)
constraints: requirements.yml:3 pins '>=9.0.0,<10.0.0' (change it to allow 12.0.0)
used modules (7): git_config, proxmox_kvm, consul_acl, slack, rhsm_repository (playbooks/site.yml); timezone (roles/common/tasks/main.yml); ufw (roles/webapp/tasks/main.yml, via short name ufw)
BREAKING (5):
  playbooks/site.yml:17 community.general.git_config: option list_all removed (line 19)
  playbooks/site.yml:17 community.general.git_config: name is newly required, not set
  playbooks/site.yml:23 community.general.proxmox_kvm: moved to community.proxmox.proxmox_kvm; community.proxmox is not installed (add it to requirements.yml)
  playbooks/site.yml:31 community.general.consul_acl: removed in 10.0.0 (tombstone): Use community.general.consul_token and/or community.general.consul_policy instead.
  playbooks/site.yml:43 community.general.rhsm_repository: state=present no longer accepted (choices: enabled, disabled) (line 45)
BEHAVIOR CHANGES (1):
  playbooks/site.yml:37 community.general.slack: prepend_hash not set; default 'auto' -> 'never'
syntax-check with 12.0.0 (playbooks/site.yml): first error playbooks/site.yml:22: couldn't resolve module/action 'community.general.proxmox_kvm' (syntax-check stops at the first error and does not check options)
verdict: BREAKING (5)

快速开始

**1. 确保服务可以运行 ansible-core。**在 macOS / Linux 上，将 ansible-core（以及可选的 ansible-lint）放在 PATH 中，或放在由 ANSIBLE_MCP_BIN_DIR 指定的 venv 中。在 Windows 上，请在 WSL 中运行：

# inside WSL (any distro); a venv under $HOME survives WSL restarts, /tmp does not
python3 -m venv ~/.venvs/ansible && ~/.venvs/ansible/bin/pip install ansible-core ansible-lint

**2. 添加服务。**在项目中使用 Claude Code：

# macOS / Linux
claude mcp add ansible -- npx -y @yawlabs/ansible-mcp@latest

# Windows (Ansible inside WSL)
claude mcp add ansible -e ANSIBLE_MCP_COMMAND_PREFIX='["wsl.exe","-d","Ubuntu","--exec"]' -e ANSIBLE_MCP_BIN_DIR=/home/me/.venvs/ansible/bin -- cmd /c npx -y @yawlabs/ansible-mcp@latest

或者将其添加到项目中的 .mcp.json（也可以放在任意位置，并设置 ANSIBLE_MCP_DIR）：

macOS / Linux：

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

Windows（在 WSL 中运行 Ansible）：

{
  "mcpServers": {
    "ansible": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@yawlabs/ansible-mcp@latest"],
      "env": {
        "ANSIBLE_MCP_COMMAND_PREFIX": "[\"wsl.exe\",\"-d\",\"Ubuntu\",\"--exec\"]",
        "ANSIBLE_MCP_BIN_DIR": "/home/me/.venvs/ansible/bin"
      }
    }
  }
}

**为什么 Windows 上需要额外步骤？**从 Node 20 开始，child_process.spawn 无法直接执行 .cmd 文件（Windows 上的 npx 就是这种文件）。用 cmd /c 包装是标准解决方法。

3. 重启 MCP 客户端，并提出例如这样的问题：“添加一个用 ufw 开放 8443 端口的任务——先对照我们已安装的 collections 检查参数。”

Windows 和 WSL，详解

• 前缀必须使用 wsl.exe --exec（或 -e），绝不能使用 --：使用 -- 时，WSL 会用 bash 重新解析参数，像 it's 这样的值会导致命令出错。服务会拒绝不带 --exec 的前缀。
• Windows 环境中的任何内容都不会传入 WSL。Ansible 端需要的变量（代理、ANSIBLE_COLLECTIONS_PATH）会通过 ANSIBLE_MCP_PASS_ENV 按名称转发。
• Windows 路径会根据 wslpath 报告的挂载根目录进行转换（C:\work\site -> /mnt/c/work/site）。项目也可以位于 WSL 内：将 dir 设为 \\wsl.localhost\Ubuntu\home\me\site（发行版必须与前缀的 -d 匹配）。
• 在 Windows 驱动器上，WSL 会将每个文件夹都视为所有用户可写，因此 Ansible 会忽略 ansible.cfg。如果项目中有该文件，服务会显式将 ANSIBLE_CONFIG 设为该文件的路径，并说明这一点。
• 服务的 Ansible 端缓存位于 WSL 用户的 ~/.cache/ansible-mcp 下（绝不使用 /tmp，因为 WSL 会在重启时清空它）。

告诉你的 Agent 如何使用

将以下内容粘贴到项目的 CLAUDE.md（或 AGENTS.md）中：

## Ansible

Module options drift between collection versions. Use the ansible MCP server:

- Call `ansible_project_info` once per session.
- Before writing or editing a task, call `ansible_module_doc` for its module, then
  run `ansible_check_task_args` on the task (or the file). Fix every problem it
  reports; quote values it flags as YAML 1.1 traps.
- Before using a role, read `ansible_role_interface`.
- Before bumping a collection in requirements.yml, run `ansible_upgrade_impact`.
- Never run plays, `--check` or `ansible-lint --fix` on your own; ask first.

配置

所有配置项均为可选。

Env var	默认值	用途
ANSIBLE_MCP_DIR	服务的工作目录	工具调用未传入 dir 时使用的项目。
ANSIBLE_MCP_COMMAND_PREFIX	（未设置：原生运行）	添加到每条 Ansible 命令前的 JSON 数组，例如 ["wsl.exe","-d","Ubuntu","--exec"]。不以 [ 开头的值会按空格拆分。Windows 上必需。
ANSIBLE_MCP_BIN_DIR	（未设置：PATH）	Ansible 端存放 ansible-* 的目录（虚拟环境的 bin）。也会将其放到子进程 PATH 的首位（ansible-lint 需要与其位于同一目录的 ansible-playbook）。
ANSIBLE_MCP_PATH_STYLE	auto	wsl 或 native。如果前缀以 wsl/wsl.exe 开头，auto 就是 wsl。其他前缀（ssh、docker exec）会使用 env -C <dir> ...，并尽力而为。
ANSIBLE_MCP_PASS_ENV	（未设置）	在前缀模式下，要转发到 Ansible 端的服务环境变量名称，以逗号分隔。
ANSIBLE_MCP_TIMEOUT_MS	120000	超过此时长后终止任何 Ansible 命令（升级下载的时限为其 3 倍）。
ANSIBLE_MCP_CACHE	~/.cache/ansible-mcp	服务端缓存（原生模式下也包括 Ansible 端缓存）：虚拟 vault 文件、本地临时文件和升级目标。可以安全删除。
ANSIBLE_MCP_REMOTE_CACHE	Ansible 端的 $HOME/.cache/ansible-mcp	前缀模式下的 Ansible 端缓存。
ANSIBLE_MCP_ALLOW_DYNAMIC_INVENTORY	（未设置）	设为 1 可重新启用脚本、构建型和插件型清单来源（它们会运行代码，并可能调用云 API）。
ANSIBLE_MCP_ALLOW_PLAY_LOOKUPS	（未设置）	设为 1 后，允许解析在 play 级别的 name / hosts / vars_files 中包含查找的 playbook（Ansible 会在此机器上执行这些查找）。

运行时（oam 或 Node）：

ansible-mcp 命令在找到可用的 oam 时优先使用它，否则会在 Node 上运行。它绝不会在低于 0.19.0 的 oam 上提供服务。

Env var	默认值	用途
ANSIBLE_MCP_RUNTIME	auto	auto：使用版本为 0.19.0 或更高的最新 oam，否则使用 Node。oam：使用 oam，否则报错退出。node：始终使用 Node——当问题只在 oam 下出现时，可用此选项绕过。
OAM_BIN	（未设置）	要使用的 oam 二进制文件路径。否则，启动器会检查 OAM_INSTALL_DIR、已安装位置（~/.oam/bin，以及 Windows 上的 %LOCALAPPDATA%\oam\bin）和 PATH，并选择最新版本。

过时的 oam 可通过 oam self-update 修复。在默认使用 oam 运行服务的 Yaw MCP 下，运行 yaw-mcp set <namespace> runtime=node 可将此服务切换到 Node。没有 --permission 沙箱选项：服务会启动 Ansible，并读取调用所指定的任何目录，因此没有可授予的有限权限。

要求

• Node.js 20+
• 控制节点上安装了 ansible-core（已验证 2.21.5）；ansible_lint_summary 需要 ansible-lint（已验证 26.10.1）
• Windows：使用安装了 ansible-core 的 WSL 发行版，并设置 ANSIBLE_MCP_COMMAND_PREFIX。未设置时，只有 ansible_project_info（静态部分）和 ansible_role_interface（本地文件）会响应；其余工具会说明需要设置什么。
• ansible_upgrade_impact：首次请求某个目标版本时，需要能够访问 Galaxy（或你配置的服务器）；之后该版本的运行可离线进行

贡献

git clone https://github.com/YawLabs/ansible-mcp.git
cd ansible-mcp
npm install
npm run lint       # Biome check
npm run lint:fix   # Auto-fix
npm run build      # tsup bundle + declarations
npm test           # Vitest (integration tests run only when Ansible is reachable)
npm run typecheck  # oam check . when oam is installed, else tsc --noEmit
npm run check:oam-floor  # the oam floor agrees across the repo and matches the latest oam release

完整工作流程（包括发布流程）请参阅 CONTRIBUTING.md。

许可证

MIT