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原生方法。

MCP Ansible Server

快速接入

详细介绍

工具参考（详细）

故障排除套件参考手册

基础工具

智能诊断

自动化与自我修复

网络与安全

性能与监控

故障排除套件的关键特性

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

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

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

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

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

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

MCP Ansible Server

快速接入

详细介绍

工具参考（详细）

故障排除套件参考手册

基础工具

智能诊断

自动化与自我修复

网络与安全

性能与监控

故障排除套件的关键特性

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

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

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

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

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

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

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

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

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

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

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