Ansible MCP Server

@yawlabs/ansible-mcp

ワンクリックでローカルの Yaw MCP 設定に追加され、すべての Yaw Terminal セッションで利用できるようになります。または、以下の手順で手動インストールしてください。

この Ansible チェックアウトが、このコントロールノードで実際にどのような状態なのかを確認できます。インストール済みモジュールの正確なオプション仕様（コーディングエージェントがコレクションのバージョンに存在しないオプションを書かないようにします）、タスク引数の検査、ロールのインターフェース、インベントリの構造と変数（秘匿化済み）、プレイの構造、有効な設定、要件の差異、コレクションのアップグレードでタスクが受ける影響を把握できます。 読み取り専用です。プレイも --check も実行せず、管理対象ホストにも接続せず、Vault のシークレットも提供しません。Red Hat のサーバーを置き換えるのではなく、補完するものです。AAP MCP はコントローラー上の状態に答え、ADT MCP は操作（--fix による lint、navigator の実行、スキャフォールディング、EE のビルド）を行います。併用してください。

Yaw Labs が開発・保守しています。

これを選ぶ理由

チェックアウトには community.general 9.5.2 が含まれていますが、モデルの学習データに含まれるのは、モデルが最もよく見かけたバージョンです。そのため、エージェントは git_config: list_all: true（11.0.0 で削除済み）を書いたり、name を忘れたり（12.0.0 以降は必須）、rhsm_repository に state: present を指定したりします（現在は受け付けられません）。VS Code の言語サーバーは正確な仕様を把握していますが、エディター上でそれを確認できるのは人間だけです。このサーバーを使えば、エージェントがコードを書く前に、インストール済みの内容に基づいて確認できます。

• 最新ではなくインストール済みの内容 — 信頼できる情報源は、コレクションのパスに対して実行する ansible-doc --json です。リダイレクト（ufw → community.general.ufw）と tombstone も解決します。
• lint が見逃す項目を検査 — ansible-lint の args ルールは、アクションプラグインを持つモジュール（copy、template）をスキップします。ansible_check_task_args は、それらの不明なオプションや不正な値を検出し、ansible-doc では表現できないオプション間のルールを明確に示します。
• YAML 1.1 に対応 — Ansible は YAML 1.1 を解析するため、引用符で囲まれていない off は false になり、0755 は整数の 493 になります。このサーバーも同じ方法で YAML を読み取り、バグの可能性が高い場合に知らせます。
• 設計上、読み取り専用 — 設定された Vault パスワードスクリプトは実行されません（サーバーが管理するダミーのパスワードファイルに置き換えます）。スクリプトとプラグインによるインベントリソースはデフォルトで無効です。また、プレイレベルのルックアップは Ansible がプレイブックを解析する前に拒否されます（事前スキャンで完全に読み取れないプレイブックや lint の対象も同様です）。
• コレクションのアップグレードによる影響 — 対象バージョンを専用キャッシュにのみダウンロードし、タスクが実際に使用しているモジュールの引数仕様を差分比較して、ファイルと行番号に関連付けます。
• macOS、Linux、WSL 経由の Windows に対応 — Ansible は Windows をコントロールノードとしてサポートしていません。Windows では、サーバーは wsl.exe --exec 経由で Ansible を起動します（シェルは一切使用しません）。

ツール

ツール	機能
ansible_project_info	ansible-core のバージョン、有効な設定ファイル、コレクションとロールのパス、インストール済みの ansible-* バイナリ、検出されたプレイブック、インベントリ（ファイル全体の Vault 数を含む）、ロール、requirements ファイルを確認します。最初に呼び出してください。
ansible_module_doc	インストール済みの単一モジュールまたはプラグインのすべてのオプションを確認します。型、必須かどうか、デフォルト値、選択肢、エイリアス、サブオプション、非推奨情報、提供元コレクションのバージョン、[has action plugin]、戻り値、（任意で）例が含まれます。
ansible_module_search	インストール済みのモジュール／プラグインを名前または説明から検索し、完全一致、接頭辞、トークン、説明の順に順位付けします。
ansible_check_task_args	インラインのタスク YAML、またはタスクファイル／プレイブックをインストール済みのドキュメントと照合します。不明なオプション、必須オプションの不足（エイリアスも対象）、無効な選択肢や型、サブオプション、mode: 0755、非推奨オプション、重複キーを確認します。「有効」と断言することはありません。ansible-doc で確認できない項目を明示します。
ansible_role_interface	ロールの argument_specs エントリポイントとオプション、デフォルト値（秘匿化し、no_log を尊重）、ドキュメントに記載のないデフォルト値、依存関係、変数名、galaxy_info を確認します。ローカルロールと ns.collection.role が対象です。
ansible_inventory	グループ、ホスト、インベントリレベルの変数（名前または値）を確認します。常に秘匿化されます。ファイル全体が Vault で暗号化されている場合は、失敗する代わりにファイル単位の表示に切り替わります。
ansible_playbook_structure	--syntax-check を実行した後、プレイ、一致したホスト、モジュールと file:line を含むタスク、タグ、解析時に Ansible が出力した非推奨警告を表示します。
ansible_config	出所（ansible.cfg、環境変数、デフォルト値）を含む有効な設定を確認します。Galaxy の認証情報は常に秘匿化され、安全のためサーバーが上書きする設定にはフラグが付けられます。
ansible_collections	requirements.yml とインストール済みのコレクションを比較し、file:line、Galaxy の制約の意味、コレクションパス間でシャドーイングされているコピーとともに、ok／VIOLATES／MISSING を表示します。
ansible_lint_summary	ansible-lint --offline の結果をルール別にグループ化し、件数、重大度、場所を表示します。修正は行いません。
ansible_upgrade_impact	コレクションを特定のバージョンに更新した場合に、このプロジェクトのタスクで何が壊れるかを確認します。削除／移動されたモジュール（runtime.yml のリダイレクトと tombstone）、削除されたオプションとエイリアス、新たに必須となるオプション、削除された選択肢、型とデフォルト値の変更、requirements の制約、requires_ansible、ターゲットに対する任意の構文チェック、判定が含まれます。

すべてのツールは任意の dir（プロジェクト）を受け取ります。ツール名には ansible_ 接頭辞が付き、ADT MCP の名前（ansible_lint、ansible_navigator など）を再利用しないため、両方を 1 つのアグリゲーターの背後に配置できます。

権限の分担

項目	担当
コントローラーのジョブ、ジョブテンプレート、コントローラーのインベントリ、RBAC	AAP MCP
スキャフォールドの内容、ansible-lint --fix、ansible-navigator による実行、venv または EE のセットアップ	ADT MCP
人が行う対話的な編集	VS Code Ansible 拡張機能（言語サーバー）
意図に基づく新しいコンテンツの生成	Ansible Lightspeed
ホストに対するモジュールの実行	このサーバーでは対応していません
インストール済みの仕様、タスク引数の妥当性、ロールのインターフェース、ローカルインベントリ、プレイの構成、有効な設定、依存関係の差異、コレクションのアップグレードによる影響	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 トークンファイルは、サーバーのキャッシュにリダイレクトされます。唯一の残留物は、存在しない場合に Ansible が空の ~/.ansible を作成することと、存在しない場合に ansible-lint が空の ~/.ansible/roles / ~/.ansible/collections を作成することです。
• Vault： シークレットが渡されることはなく、ansible.cfg に指定された vault_password_file / vault_identity_list スクリプトも実行されません（ランダムなパスワードを保持するサーバー管理のファイルに置き換えられます）。インラインの !vault 値は <vaulted> として表示されます。ファイル全体が Vault で暗号化されている場合は、読み取らずに一覧表示します。
• 動的インベントリ（スクリプト、構築済みインベントリ、クラウドプラグイン）はコードを実行して 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 トークン。URL のパスワードはその場でマスク）が対象です。Galaxy サーバーのトークンとパスワードは常に秘匿化されます。「シークレットを表示」する切り替え機能はありません。
• ネットワーク： キャッシュにない場合の 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 では、PATH 上に ansible-core（および任意で ansible-lint）を配置するか、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（あるいは任意の場所にある .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 を開くタスクを追加してください。まず、インストール済みのコレクションに照らして引数を確認してください。」

Windows と WSL の詳細

• プレフィックスには wsl.exe --exec（または -e）を使用する必要があります。-- は使用しないでください。-- を使うと、WSL が bash で引数を再解析するため、it's のような値があるとコマンドが壊れます。サーバーは --exec のないプレフィックスを拒否します。
• Windows 環境の情報は WSL に引き継がれません。プロキシや ANSIBLE_COLLECTIONS_PATH など、Ansible 側で必要な変数は、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.cfg がある場合、サーバーは明示的に ANSIBLE_CONFIG を設定し、その旨を通知します。
• サーバーの Ansible 側キャッシュは、WSL ユーザーの ~/.cache/ansible-mcp にあります。WSL の再起動時に消去される /tmp は使用しません。

エージェントに使い方を伝える

以下をプロジェクトの 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.

設定

すべて任意です。

環境変数	デフォルト	用途
ANSIBLE_MCP_DIR	サーバーの作業ディレクトリ	ツール呼び出しで dir が渡されない場合に使用するプロジェクトです。
ANSIBLE_MCP_COMMAND_PREFIX	（未設定：ネイティブ）	すべての Ansible コマンドの先頭に付加する JSON 配列です。例：["wsl.exe","-d","Ubuntu","--exec"]。[ で始まらない値は空白で分割されます。Windows では必須です。
ANSIBLE_MCP_BIN_DIR	（未設定：PATH）	ansible-* を含む Ansible 側のディレクトリ（venv の bin など）です。子プロセスの PATH の先頭にも設定してください（ansible-lint が同じ場所にある ansible-playbook を必要とします）。
ANSIBLE_MCP_PATH_STYLE	auto	wsl または native。auto は、プレフィックスが wsl／wsl.exe で始まる場合に 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 を設定すると、プレイレベルの name／hosts／vars_files にルックアップを含むプレイブックの解析を許可します（Ansible はこのマシン上でそのルックアップを実行します）。

ランタイム（oam または Node）：

ansible-mcp コマンドは、使用可能な oam が見つかった場合はそれを優先し、見つからない場合は Node で実行します。0.19.0 より古い oam では、サーバーを起動しません。

環境変数	デフォルト	用途
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（または設定済みのサーバー）に接続できる必要があります。そのバージョンでの2回目以降の実行はオフラインで行えます。

貢献

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