mcp- ansible自动化工具

【技术文档摘要】： MCP Ansible Server

高级Ansible模型上下文协议（MCP）服务器，用Python编写，提供Ansible工具用于清单、剧本、角色和项目工作流。

快速开始

git clone https://github.com/bsahane/mcp-ansible.git
cd mcp-ansible

# 创建并激活Python虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 通过requirements.txt安装依赖
python -m pip install -U pip
pip install -r requirements.txt

# （可选）本地安装项目包
pip install -e .

# 运行MCP服务器
python src/ansible_mcp/server.py

需求

• Python 3.10+
• macOS/Linux

设置

cd /Users/bsahane/Developer/cursor/mcp-ansible
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
pip install "mcp[cli]>=1.2.0" "PyYAML>=6.0.1" "ansible-core>=2.16.0"
pip install -e .

运行服务器

python src/ansible_mcp/server.py

Cursor配置（/Users/bsahane/.cursor/mcp.json）

{
  "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"
      }
    }
  }
}

Claude for Desktop配置

添加到~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "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"
      }
    }
  }
}

工具（名称）

核心Ansible工具：

• create-playbook: 从YAML字符串或字典创建剧本
• validate-playbook: 验证剧本语法（ansible-playbook --syntax-check）
• ansible-playbook: 执行剧本
• ansible-task: 运行临时任务（默认连接=本地主机）
• ansible-role: 通过生成的临时剧本执行角色
• create-role-structure: 构建角色目录树
• ansible-inventory: 列出库存主机和组
• register-project: 注册一个Ansible项目以方便重用
• list-projects: 显示已注册的项目及其默认值
• project-playbooks: 发现项目根下的剧本
• project-run-playbook: 使用已注册项目的库存/环境运行剧本

本地库存套件（无AAP/AWX）：

• inventory-parse: 解析库存（ansible.cfg感知），返回主机/组/主机变量
• inventory-graph: 显示组/主机图
• inventory-find-host: 显示主机的组和合并变量
• ansible-ping: 临时ping模块
• ansible-gather-facts: 运行setup并返回解析的事实
• validate-yaml: 验证YAML文件并带有错误位置
• galaxy-install: 从需求安装角色/集合
• project-bootstrap: Galaxy安装+环境检查

高级故障排除套件：

基础工具：

• ansible-remote-command: 执行任意shell命令并增强输出解析
• ansible-fetch-logs: 获取并分析日志文件，具有模式检测和关联
• ansible-service-manager: 管理服务，具有状态检查和日志关联

智能诊断：

• ansible-diagnose-host: 综合健康评估，带有评分和建议
• ansible-capture-baseline: 捕获系统状态快照以供比较
• ansible-compare-states: 时间旅行调试与基线比较

自动化及自我修复：

• ansible-auto-heal: 带有安全检查的智能自动问题解决

网络与安全：

• ansible-network-matrix: 在主机之间进行全面的网络连通性测试
• ansible-security-audit: 安全漏洞评估和合规性检查

性能与监控：

• ansible-health-monitor: 带有趋势分析和异常检测的持续监控
• ansible-performance-baseline: 性能基准测试和回归检测
• ansible-log-hunter: 多源高级日志关联和模式搜索

环境变量（可选）

• MCP_ANSIBLE_PROJECT_ROOT: 绝对项目根
• MCP_ANSIBLE_INVENTORY: 库存路径或目录
• MCP_ANSIBLE_PROJECT_NAME: 环境项目的标签
• MCP_ANSIBLE_ROLES_PATH: 分号分隔的角色路径
• MCP_ANSIBLE_COLLECTIONS_PATHS: 分号分隔的集合路径
• MCP_ANSIBLE_ENV_<KEY>: 转发到进程环境（例如，MCP_ANSIBLE_ENV_ANSIBLE_CONFIG）

示例（Claude工具）

• 列出库存中的主机：

  • 工具：ansible-inventory
  • 参数：inventory = "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"

• 运行简单的剧本：

  • 工具：ansible-playbook
  • 参数：
    • playbook_path: 绝对路径到playbook.yml
    • inventory: "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"

• 临时ping本地主机：

  • 工具：ansible-task
  • 参数：
    • host_pattern: "localhost"
    • module: "ping"
    • inventory: "localhost,"

• 构建一个角色：

  • 工具：create-role-structure
  • 参数：
    • base_path: "/tmp"
    • role_name: "demo_role"

• 注册一个项目并运行项目剧本：

  • 工具：register-project
    • name: "projectAIOPS"
    • root: "/Users/bsahane/GitLab/projectAIOPS/mcp--ansible-server"
    • inventory: "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"
    • make_default: true
  • 工具：project-playbooks
    • project: "projectAIOPS"
  • 工具：project-run-playbook
    • playbook_path: 从发现列表中获取绝对路径

本地库存套件示例

• 通过ansible.cfg解析多个库存（合并group_vars/host_vars）：

  • 工具：inventory-parse
  • 参数：
    • ansible_cfg_path: "/abs/path/to/ansible.cfg"
    • include_hostvars: true

• 解析特定扩展名的库存文件：

  • 工具：inventory-parse
  • 参数：
    • project_root: "/abs/path/to/project"
    • inventory_paths: ["/abs/path/to/project/inventories/stage/inventory"]
    • include_hostvars: true

• 从库存中ping一组：

  • 工具：ansible-ping
  • 参数：
    • project_root: "/abs/path/to/project"
    • host_pattern: "aws_mx_ext_stage"

注意事项

• 服务器使用stdio传输。不要打印到stdout；日志发送到stderr。
• Ansible连接/认证遵循您的本地Ansible配置。

参考

• MCP快速入门（Python）：https://modelcontextprotocol.io/quickstart/server#python

工具参考（详细）

以下是所有工具的简短描述、最少参数、您可以在MCP UI中询问的一个示例问题以及一个样本答案。

• create-playbook: 从YAML字符串或对象创建Ansible剧本文件

  • 最少参数：

    { "playbook": [{"hosts":"all","tasks":[{"debug":{"msg":"hi"}}]}] }
    

  • 示例问题："创建一个在所有主机上打印hello的剧本。"
  • 可能的答案：{ "path": "/tmp/playbook_x.yml", "bytes_written": 123, "preview": "- hosts: all..." }

• validate-playbook: 检查剧本语法

  • 最少参数：

    { "playbook_path": "/abs/playbook.yml" }
    

  • 示例问题："这个剧本是否语法正确？"
  • 可能的答案：{ "ok": true, "rc": 0 }

• ansible-playbook: 运行一个剧本

  • 最少参数：

    { "playbook_path": "/abs/playbook.yml", "inventory": "localhost," }
    

  • 示例问题："在这个剧本中运行localhost。"
  • 可能的答案：{ "ok": true, "rc": 0, "stdout": "PLAY [all]..." }

• ansible-task: 运行一个临时模块

  • 最少参数：

    { "host_pattern": "localhost", "module": "ping", "inventory": "localhost," }
    

  • 示例问题："ping localhost。"
  • 可能的答案：{ "ok": true, "stdout": "pong" }

• ansible-role: 通过临时剧本执行一个角色

  • 最少参数：

    { "role_name": "myrole", "hosts": "localhost", "inventory": "localhost," }
    

  • 示例问题："在localhost上运行角色myrole。"
  • 可能的答案：{ "ok": true, "rc": 0 }

• create-role-structure: 构建角色目录树

  • 最少参数：

    { "base_path": "/tmp", "role_name": "demo" }
    

  • 示例问题："创建名为demo的Ansible角色骨架。"
  • 可能的答案：{ "created": [".../tasks/main.yml", ...], "role_path": "/tmp/demo" }

• ansible-inventory: 列出库存中的主机和组

  • 最少参数：

    { "inventory": "/abs/inventory" }
    

  • 示例问题："列出这个库存中的主机。"
  • 可能的答案：{ "hosts": ["host01"], "groups": {"web": ["host01"]} }

• register-project: 注册一个Ansible项目以便重用

  • 最少参数：

    { "name": "proj", "root": "/abs/project", "make_default": true }
    

  • 示例问题："注册我的项目根并使其成为默认值。"
  • 可能的答案：{ "path": "~/.config/mcp-ansible/config.json", "projects": ["proj"] }

• list-projects: 显示已注册的项目

  • 最少参数：{}
  • 示例问题："哪些项目已注册，哪个是默认值？"
  • 可能的答案：{ "default": "proj", "projects": {"proj": {"root": "/abs"}} }

• project-playbooks: 发现项目根下的剧本

  • 最少参数：

    { "project": "proj" }
    

  • 示例问题："列出我的项目中的剧本。"
  • 可能的答案：{ "ok": true, "playbooks": ["/abs/x.yml", "/abs/y.yml"] }

• project-run-playbook: 使用项目库存/环境运行剧本

  • 最少参数：

    { "playbook_path": "/abs/x.yml", "project": "proj" }
    

  • 示例问题："在我的默认项目中运行x.yml。"
  • 可能的答案：{ "ok": true, "rc": 0 }

• inventory-parse: 解析库存（ansible.cfg感知，合并group_vars/host_vars）

  • 最少参数：

    { "project_root": "/abs/project", "include_hostvars": true }
    

  • 示例问题："从我的项目根解析所有主机和变量。"
  • 可能的答案：{ "hosts": ["h1"], "groups": {"web":["h1"]}, "hostvars": {"h1": {...}} }

• inventory-graph: 显示库存图

  • 最少参数：

    { "project_root": "/abs/project" }
    

  • 示例问题："显示库存图。"
  • 可能的答案："@all\n |--@web\n | |--h1"

• inventory-find-host: 显示主机的组和合并变量

  • 最少参数：

    { "project_root": "/abs/project", "host": "h1" }
    

  • 示例问题："h1有哪些组和变量？"
  • 可能的答案：{ "groups": ["web"], "hostvars": {"ansible_user":"root"} }

• ansible-ping: 通过临时方式ping主机

  • 最少参数：

    { "project_root": "/abs/project", "host_pattern": "localhost" }
    

  • 示例问题："ping localhost。"
  • 可能的答案：{ "ok": true, "rc": 0 }

• ansible-gather-facts: 运行setup并返回事实

  • 最少参数：

    { "project_root": "/abs/project", "host_pattern": "localhost" }
    

  • 示例问题："从localhost收集事实。"
  • 可能的答案：{ "facts": {"localhost": {"ansible_hostname":"node"}} }

• validate-yaml: 验证YAML文件

  • 最少参数：

    { "paths": ["/abs/file.yml"] }
    

  • 示例问题："验证这个YAML文件。"
  • 可能的答案：{ "ok": true, "results": [{"path":"/abs/file.yml","ok":true}] }

• galaxy-install: 从需求安装角色/集合

  • 最少参数：

    { "project_root": "/abs/project" }
    

  • 示例问题："为我的项目安装galaxy依赖项。"
  • 可能的答案：{ "ok": true, "executed": [{"kind":"collection","rc":0}] }

• project-bootstrap: 初始化项目（环境信息+galaxy安装）

  • 最少参数：

    { "project_root": "/abs/project" }
    

  • 示例问题："初始化我的项目。"
  • 可能的答案：{ "ok": true, "details": {"ansible_version":"..."} }

• inventory-diff: 比较两个库存

  • 最少参数：

    { "left_project_root": "/abs/project", "right_project_root": "/abs/project" }
    

  • 示例问题："stage和prod库存之间有什么变化？"
  • 可能的答案：{ "added_hosts": [], "removed_hosts": [], "group_membership_changes": {} }

• ansible-test-idempotence: 运行两次剧本并断言第二次没有更改

  • 最少参数：

    { "playbook_path": "/abs/playbook.yml", "project_root": "/abs/project" }
    

  • 示例问题："这个剧本是否幂等？"
  • 可能的答案：{ "ok": true, "changed_total_second": 0 }

• galaxy-lock: 生成已安装角色/集合的锁文件

  • 最少参数：

    { "project_root": "/abs/project" }
    

  • 示例问题："为我的项目创建一个requirements.lock.yml。"
  • 可能的答案：{ "ok": true, "path": "/abs/requirements.lock.yml" }

• vault-encrypt / vault-decrypt / vault-view / vault-rekey: 密码操作

  • 最少参数（加密）：

    { "file_paths": ["/abs/group_vars/all/vault.yml"], "project_root": "/abs/project" }
    

  • 示例问题："使用我的密码加密group_vars/all/vault.yml。"
  • 可能的答案：{ "ok": true, "rc": 0 }

故障排除套件参考

基础工具

• ansible-remote-command: 执行shell命令并增强解析

  • 最少参数：

    { "host_pattern": "webserver", "command": "ps aux | grep nginx" }
    

  • 示例问题："显示webserver上的所有nginx进程。"
  • 样本答案：{ "ok": true, "stdout": "Process list...", "parsed_output": {...} }

• ansible-fetch-logs: 获取并分析日志文件

  • 最少参数：

    { "host_pattern": "app*", "log_paths": ["/var/log/nginx/error.log"], "analyze": true }
    

  • 示例问题："获取nginx错误日志的最后100行并分析模式。"
  • 样本答案：{ "ok": true, "logs": {...}, "summary": {"total_logs": 1, "successful": 1} }

• ansible-service-manager: 具有日志的服务管理

  • 最少参数：

    { "host_pattern": "web", "service_name": "nginx", "action": "restart", "check_logs": true }
    

  • 示例问题："重启nginx服务并显示最近的日志。"
  • 样本答案：{ "ok": true, "action_result": {...}, "status": {...}, "logs": {...} }

智能诊断

• ansible-diagnose-host: 综合健康评估
  • 最少参数：

    { "host_pattern": "production", "checks":