Ansible服务器工具

MCP Ansible 服务器

在Python中实现的高级Ansible模型上下文协议（MCP）服务器，用于公开Ansible的库存、剧本、角色和项目工作流实用工具。

快速入门

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

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

# Install dependencies via requirements.txt
python -m pip install -U pip
pip install -r requirements.txt

# (Optional) install the project package locally
pip install -e .

# Run the MCP server
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

光标配置（/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的配置

添加到 ~/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字符串或字典创建剧本
• 验证剧本：验证剧本语法（使用 ansible-playbook --syntax-check）
• ansible-playbook：执行剧本（playbooks）
• Ansible 任务：运行即席任务（默认情况下，对于本地主机，连接方式为本地）
• Ansible角色：通过生成的临时playbook执行角色
• 创建角色结构：搭建角色目录树
• ansible-inventory：列出库存主机和组
• 注册项目：注册一个Ansible项目以便轻松重用
• list-projects: 显示已注册的项目和默认项目
• 项目剧本：在项目根目录下发现剧本
• project-run-playbook：使用已注册项目的库存/环境运行一个剧本（playbook）

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

• `inventory-parse`: 解析清单文件（支持ansible.cfg配置），返回主机/组/主机变量
• 库存图表：显示组/主机图表
• `inventory-find-host`：显示主机所属的组和合并的变量
• ansible-ping：临时ping模块
• ansible-gather-facts：运行设置并返回解析后的事实信息
• validate-yaml：验证YAML文件并指出错误位置
• galaxy-install：从需求中安装角色/集合
• project-bootstrap：银河系安装 + 环境检查

高级故障排除工具集：

基础工具：

• 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_ 可以翻译为“MCP_ANSIBLE 环境_”（注：这里的“_”可能表示一个未完成的变量名或是一个占位符，实际翻译时可能需要根据上下文来确定其具体含义或是否需要省略）。如果“_”是可省略的，那么翻译结果就是“MCP_ANSIBLE 环境”转发到进程环境变量（例如，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 的绝对路径
    • 库存文件（或清单文件）: "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"

• 临时ping本地主机：

  • 工具：ansible-task
  • 参数：
    • 主机模式： "localhost"
    • 模块： "ping"
    • 库存："localhost,"

• 构建角色框架：

  • 工具：创建角色结构
  • 参数：
    • base_path: "/tmp" 翻译成中文为：基础路径: "/tmp"
    • 角色名称: "示例角色"

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

  • 工具：register-project（注册项目）
    • 名称：projectAIOPS
    • 根目录: "/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server"
    • 库存文件路径："/Users/bsahane/GitLab/projectAIOPS/mcp-ansible-server/inventory/hosts.ini"
    • make_default: true 翻译为中文是：“设为默认：真” 或 “作为默认设置：是”
  • 工具：project-playbooks（项目剧本/项目操作手册）
    • 项目：项目AIOPS
  • 工具：project-run-playbook（项目运行剧本/计划）
    • playbook_path：从发现列表中获取的绝对路径

本地库存套件的示例

• 通过 ansible.cfg 解析多个清单文件（合并 group_vars/host_vars）：

  • 工具：库存解析
  • 参数：
    • ansible_cfg_path: "/绝对路径/to/ansible.cfg" （注：实际路径应替换为具体的绝对路径，此处“/abs/”仅为示意，实际翻译时应根据具体情况填写完整路径）
    • 包含主机变量：true

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

  • 工具：库存解析
  • 参数：
    • 项目根目录: "/abs/path/to/project"
    • 库存路径: ["/abs/path/to/project/inventories/stage/inventory"]
    • include_hostvars: true 的中文翻译是：“包含主机变量：真”

• 从库存中ping一个群组：

  • 工具：ansible-ping
  • 参数：
    • 项目根目录: "/abs/path/to/project"
    • 主机模式：`aws_mx_ext_stage`

注释

• 服务器使用stdio传输方式。请不要将信息打印到标准输出；日志应输出到标准错误。
• Ansible 的连接/认证遵循您本地的 Ansible 配置。

参考

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

工具参考（详细）

以下是所有工具及其简短描述、最小参数、您可以在MCP用户界面中提出的问题示例以及示例答案。

• **创建剧本（或创建行动计划）**从YAML字符串或对象创建Ansible剧本文件

  • 最少参数：
    复制

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

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

• **验证剧本（或：校验Playbook）**检查剧本（或：剧本文件）的语法

  • 最小参数：
    复制

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

  • 示例问题：“这个剧本在语法上是有效的吗？”
  • 可能的答案： { "ok": true, "rc": 0 }

• Ansible Playbook运行一个剧本（或：执行一个操作指南/运行一个Playbook）

  • 最少参数：
    复制

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

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

• Ansible 任务运行一个临时模块

  • 最小参数：
    复制

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

  • 示例问题：“ping 本地主机。”
  • 可能的答案： { "ok": true, "stdout": "pong" }

• Ansible 角色通过临时剧本执行角色

  • 最少参数：
    复制

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

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

• 创建角色结构构建一个角色目录树

  • 最少参数：
    复制

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

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

• **Ansible 库文件（或 Ansible 清单）**从清单中列出主机和组

  • 最少参数：
    复制

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

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

• 注册项目注册一个Ansible项目以便重用

  • 最小参数：
    复制

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

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

• 列出项目显示已注册项目

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

• 项目操作手册/项目实施指南在项目根目录下发现 playbook（操作手册/剧本）

  • 最少参数：
    复制

    { "project": "proj" }
    

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

• **项目运行剧本（或操作手册）**使用项目库存/环境运行剧本

  • 最小参数：
    复制

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

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

• 库存解析解析库存文件（支持ansible.cfg，合并group_vars/host_vars）

  • 最少参数：
    复制

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

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

• 库存图表显示库存图表

  • 最少参数：
    复制

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

  • 示例问题：“显示库存图表。”
  • 可能的答案：“@全体成员\n |--@网页\n | |--h1”

• 库存查找主机显示主机的组和合并变量

  • 最小参数：
    复制

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

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

• Ansible-Ping通过临时网络ping主机

  • 最少参数：
    复制

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

  • 示例问题：“ping 本地主机。”
  • 可能的答案： { "ok": true, "rc": 0 }

• **Ansible 收集系统信息（或“Ansible 汇总事实”）**运行安装程序并返回事实信息

  • 最小参数：
    复制

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

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

• 验证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}] }

• **项目引导（或项目启动模板）**Bootstrap项目（环境信息+Galaxy安装）

  • 最少参数：
    复制

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

  • 示例问题：“为我的项目添加Bootstrap。”
  • 可能的答案： { "ok": true, "details": {"ansible_version":"..."} }

• 库存差异比较两个库存清单

  • 最小参数：
    复制

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

  • 示例问题：“测试环境和生产环境的库存之间有什么变化？”
  • 可能的答案： { "added_hosts": [], "removed_hosts": [], "group_membership_changes": {} }

• Ansible 测试幂等性运行剧本两次，并断言第二次运行时没有变化

  • 最少参数：
    复制

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

  • 示例问题：“这个操作手册是幂等的吗？”
  • 可能的答案： { "ok": true, "changed_total_second": 0 }

• 银河锁生成已安装角色/集合的锁定文件

  • 最少参数：
    复制

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

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

故障排除套件参考手册

基础工具

• Ansible远程命令执行具有增强解析功能的shell命令

  • 最小参数：
    复制

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

  • 示例问题：“显示网络服务器上所有的nginx进程。”
  • 示例答案： { "ok": true, "stdout": "Process list...", "parsed_output": {...} }

• Ansible 获取日志获取并分析日志文件

  • 最小参数：
    复制

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

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

• Ansible 服务管理器带有日志的服务管理

  • 最少参数：
    复制

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

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

智能诊断

• Ansible 主机诊断工具全面健康评估

  • 最少参数：
    复制

    { "host_pattern": "production", "checks": ["system", "network", "security"], "include_recommendations": true }
    

  • 示例问题：“对生产服务器进行全面健康检查，并给出建议。”
  • 示例答案： { "ok": true, "diagnosis": {...}, "health_score": {"score": 85, "level": "good"} }

• Ansible 基线捕获工具捕获系统状态基线

  • 最少参数：
    复制

    { "host_pattern": "web*", "snapshot_name": "pre-deployment", "include": ["configs", "processes"] }
    

  • 示例问题：“在部署前捕获基线快照。”
  • 示例答案： { "ok": true, "snapshot_id": "snapshot_20250101_120000_abc123", "categories_captured": [...] }

• **ansible-compare-states（可译为“Ansible 状态比较”）**与基线进行比较

  • 最少参数：
    复制

    { "host_pattern": "web*", "baseline_snapshot_id": "snapshot_20250101_120000_abc123" }
    

  • 示例问题：“将当前状态与部署前的基线进行比较。”
  • 参考答案： { "ok": true, "comparison": {"differences": {...}, "summary": {...}} }

自动化与自我修复

• Ansible 自动修复自动化问题解决
  • 最少参数：
    复制

    { "host_pattern": "database", "symptoms": ["high_memory", "disk_full"], "max_impact": "medium", "dry_run": true }
    

  • 示例问题：“在数据库服务器上自动修复内存和磁盘问题（预览模式）。”
  • 参考答案： { "ok": true, "proposed_actions": [...], "summary": {"actionable_symptoms": 2} }

网络与安全

• Ansible 网络矩阵网络连接测试

  • 最少参数：
    复制

    { "host_patterns": ["web*", "db*"], "check_ports": [22, 3306, 443] }
    

  • 示例问题：“测试Web服务器和数据库服务器之间的网络连接。”
  • 示例答案： { "ok": true, "network_matrix": {...}, "summary": {"source_patterns": 2, "ports_tested": [22, 3306, 443]} }

• Ansible安全审计安全漏洞评估

  • 最少参数：
    复制

    { "host_pattern": "all", "audit_categories": ["packages", "permissions", "network"], "generate_report": true }
    

  • 示例问题：“对所有服务器进行全面的安全审计。”
  • 参考答案： { "ok": true, "audit": {...}, "security_assessment": {"score": 75, "level": "warning"} }

性能与监控

• Ansible 健康监控持续监测并分析趋势

  • 最小参数：
    复制

    { "host_pattern": "production", "monitoring_duration": 300, "metrics_interval": 30 }
    

  • 示例问题：“监控生产服务器5分钟，并分析趋势。”
  • 示例答案： { "ok": true, "monitoring": {"trend_analysis": {...}, "anomalies": []} }

• Ansible 性能基线性能基准测试

  • 最小参数：
    复制

    { "host_pattern": "web*", "benchmark_duration": 60, "store_baseline": true }
    

  • 示例问题：“在Web服务器上运行性能基准测试，并将结果作为基线存储。”
  • 示例答案： { "ok": true, "baseline": {"benchmarks": {...}, "performance_assessment": {"score": 90}} }

• Ansible日志猎手高级日志关联

  • 最少参数：
    复制

    { "host_pattern": "app*", "search_patterns": ["ERROR", "CRITICAL"], "time_range": "1h", "correlation_window": 300 }
    

  • 示例问题：“搜索过去一小时内的应用日志中的错误，并关联相关事件。”
  • 示例答案： { "ok": true, "hunt_results": {...}, "correlation": {"correlated_events": 3} }

故障排除套件的关键特性

🎯（目标/靶心） 智能分析

• 健康评分基于CPU、内存、磁盘、网络和安全指标的自动化评分
• 模式识别日志模式、错误相关性和系统异常的智能分析
• 趋势检测实时监控，结合趋势分析与预测洞察

🔧 修理工具或扳手的符号，常用于表示维修、修理或相关工作的标志。 自动化修复

• 症状到解决方案的映射基于检测到的症状进行智能问题解决
• 安全第一原则分阶段响应，包含影响评估及强制性安全检查
• 干运行模式在执行前预览所有操作以进行安全验证

📊 表格/数据图表 高级分析

• 基线对比时间旅行调试，支持全面状态对比
• 性能基准测试建立基线并检测性能退化
• 安全审计全面漏洞评估及合规性评分

🛡️ 翻译成中文是“盾牌”。 企业级安全

• 影响控制可配置的影响级别（低/中/高）并附带审批工作流
• 审计轨迹/审计追踪完整记录所有故障排除操作和决策
• 回滚功能对于失败操作的自动回滚

🔄 旋转符号（表示循环、重复或刷新） 纯Ansible集成

• 无SSH依赖所有操作都通过Ansible的原生连接框架进行
• 模块一致性使用标准Ansible模块以实现最大兼容性
• 配置感知尊重 ansible.cfg 和现有项目配置

所有故障排除工具在提供企业级自动化功能的同时，均保持了相同的安全性、可审计性以及Ansible原生方法。