使用说明

MCP可解析服务器

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

工具（名称）

核心可解析工具：

创建剧本：从YAML字符串或字典创建剧本
验证剧本：验证剧本语法（可翻译剧本——语法检查）
可理解的剧本：执行剧本
ansible任务：运行ad-hoc任务（默认为本地主机的connection=local）
ansible role：通过生成的临时剧本执行角色
创建角色结构：脚手架角色目录树
ansible库存：列出库存主机和组
注册项目：注册Ansible项目以便于重用
列出项目：显示已注册的项目和默认项目
项目剧本：在项目根目录下发现剧本
项目运行剧本：使用注册项目的库存/env运行剧本

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

库存解析：解析库存（ansible.cfg感知），返回主机/组/hostvars
库存图：显示组/主机图
清点查找主机：显示主机的组和合并的变量
ansibleping：临时ping模块
ansible收集事实：运行安装程序并返回解析的事实
验证yaml：验证带有错误位置的yaml文件
galaxy install：根据需求安装角色/集合
项目引导：Galaxy安装+环境检查

高级故障排除套件：

基础工具：

ansible远程命令：使用增强的输出解析执行任意shell命令
ansible获取日志：通过模式检测和相关性获取和分析日志文件
ansible服务管理器：通过状态检查和日志关联来管理服务

智能诊断：

可靠的诊断主机：带评分和建议的综合健康评估
可分析的捕获基线：捕获系统状态快照以进行比较
可比较状态：基于基线比较的时间旅行调试

自动化和自我修复：

ansible auto-heal:智能自动解决问题，并进行安全检查

网络与安全：

ansible网络矩阵：主机之间的全面网络连接测试
ansible安全审计：安全漏洞评估和合规性检查

性能与监控：

可靠的健康监测器：通过趋势分析和异常检测进行持续监测
可靠的性能基线：性能基准测试和回归检测
ansible日志搜索器：跨多个来源的高级日志相关性和模式搜索

环境变量（可选）

MCP_ANSILE_PROJECT_ROOT：绝对项目根
MCP_ANSIBLE_INVENTORY：库存路径或目录
MCP_ANSILE_PROJECT_NAME:env项目的标签
MCP_ANSIBLE_ROLES_PATH:冒号分隔的角色路径
MCP_ANSIBLE_COLLECTIONS_PATHS:冒号分隔的集合路径
MCP_ANSIBLE_ENV_：转发到进程环境（例如，MCP_ANSIBLE_env_ANSIBLE_CONFIG）

示例（Claude Tools）

从清单中列出主机：
- 工具：可分析库存
- Args:investory=“/Users/bsahane/GitLab/projectAIOPS/mcp-ansible服务器/库存/hosts.ini”
运行一个简单的剧本：
- 工具：可理解的剧本
- Args：
  - playbook_path：playbook.yml的绝对路径
  - 库存：“/Users/bsahane/GitLab/项目AIOPS/mcp可传输服务器/库存/hosts.ini”
临时ping本地主机：
- 工具：可执行任务
- Args：
  - 主机模式：“localhost”
  - 模块：“ping”
  - 库存：“localhost”
脚手架的作用：
- 工具：创建角色结构
- Args：
  - base_path：“/tmp”
  - 角色名称：“demo_role”
注册一个项目并运行项目剧本：
- 工具：注册项目
  - 名称：“项目AIOPS”
  - root:“/Users/bsahane/GitLab/projectAIOPS/mcp-ansible服务器”
  - 库存：“/Users/bsahane/GitLab/项目AIOPS/mcp可传输服务器/库存/hosts.ini”
  - make_default：true
- 工具：项目剧本
  - 项目：“项目AIOPS”
- 工具：项目运行剧本
  - playbook_path：已发现列表的绝对路径

本地库存套件示例

使用多个库存通过ansible.cfg进行解析（合并group_vars/host_vars）：
- 工具：库存解析
- Args：
  - ansible_cfg_path：“/abs/path/to/ansible.cfg”
  - include_hostvars：true
解析特定的无扩展名库存文件：
- 工具：库存解析
- Args：
  - project_root：“/abs/path/to/project”
  - 库存路径：[“/abs/path/to/project/库存/阶段/库存”]
  - include_hostvars：true
从库存中Ping组：
- 工具：ansible ping
- Args：
  - project_root：“/abs/path/to/project”
  - 主机模式：“aws_mx.ext_stage”

备注

服务器使用stdio传输。不要打印到stdout；日志将转到stderr。
Ansible连接/身份验证遵循您的本地Ansible配置。

参考

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

工具参考（详细）

下面是所有带有简短描述、最小参数、可以在MCP UI中提问的示例问题和示例答案的工具。

创建剧本：从YAML字符串或对象创建Ansible剧本文件
- 最小参数：
```
{ "playbook": [{"hosts":"all","tasks":[{"debug":{"msg":"hi"}}]}] }
```
- 示例问题：“创建一个为所有主机打印hello的剧本。”
- 可能的答案： { "path": "/tmp/playbook_x.yml", "bytes_written": 123, "preview": "- hosts: all..." }
验证剧本：语法检查剧本
- 最小参数：
```
{ "playbook_path": "/abs/playbook.yml" }
```
- 示例问题：“这个剧本在语法上有效吗？”
- 可能的答案： { "ok": true, "rc": 0 }
可理解的剧本：运行一个剧本
- 最小参数：
```
{ "playbook_path": "/abs/playbook.yml", "inventory": "localhost," }
```
- 示例问题：“在本地主机上运行此剧本。”
- 可能的答案： { "ok": true, "rc": 0, "stdout": "PLAY [all]..." }
可执行任务：运行临时模块
- 最小参数：
```
{ "host_pattern": "localhost", "module": "ping", "inventory": "localhost," }
```
- 示例问题：“Ping localhost。”
- 可能的答案： { "ok": true, "stdout": "pong" }
可转换角色：通过临时剧本执行角色
- 最小参数：
```
{ "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" }
可靠库存：从清单中列出主机和组
- 最小参数：
```
{ "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"}} }
项目剧本：在项目根目录下发现剧本
- 最小参数：
```
{ "project": "proj" }
```
- 示例问题：“列出我项目中的剧本。”
- 可能的答案： { "ok": true, "playbooks": ["/abs/x.yml", "/abs/y.yml"] }
项目运行手册：使用项目库存/env运行剧本
- 最小参数：
```
{ "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" }
```
- 示例问题：“显示库存图。”
- 可能的答案：“@all\n|--@web\n|--h1”
库存查找主机：显示主机的组和合并的变量
- 最小参数：
```
{ "project_root": "/abs/project", "host": "h1" }
```
- 示例问题：“h1有哪些组和变量？”
- 可能的答案： { "groups": ["web"], "hostvars": {"ansible_user":"root"} }
易感ping：通过ad-hoc Ping主机
- 最小参数：
```
{ "project_root": "/abs/project", "host_pattern": "localhost" }
```
- 示例问题：“Ping localhost。”
- 可能的答案： { "ok": true, "rc": 0 }
收集事实：运行安装程序并返回事实
- 最小参数：
```
{ "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}] }
银河安装：根据需求安装角色/集合
- 最小参数：
```
{ "project_root": "/abs/project" }
```
- 示例问题：“为我的项目安装galaxy依赖项。”
- 可能的答案： { "ok": true, "executed": [{"kind":"collection","rc":0}] }
项目引导：Bootstrap项目（环境信息+银河系安装）
- 最小参数：
```
{ "project_root": "/abs/project" }
```
- 示例问题：“引导我的项目。”
- 可能的答案： { "ok": true, "details": {"ansible_version":"..."} }
库存差异：区分两种库存
- 最小参数：
```
{ "left_project_root": "/abs/project", "right_project_root": "/abs/project" }
```
- 示例问题：“阶段库存和产品库存之间发生了什么变化？”
- 可能的答案： { "added_hosts": [], "removed_hosts": [], "group_membership_changes": {} }
可检验幂等性：运行两次剧本，第二次运行时断言没有更改
- 最小参数：
```
{ "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加密/vault解密/vault视图/vault密钥更新：保险库操作
- 最小参数（加密）：
```
{ "file_paths": ["/abs/group_vars/all/vault.yml"], "project_root": "/abs/project" }
```
- 示例问题：“使用我的保管库密码加密group_vars/all/vault.yml。”
- 可能的答案： { "ok": true, "rc": 0 }

故障排除套件参考

基础工具

可传输远程命令：使用增强的解析执行shell命令
- 最小参数：
```
{ "host_pattern": "webserver", "command": "ps aux | grep nginx" }
```
- 示例问题：“显示Web服务器上的所有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": {...} }

智能诊断

可分析诊断主机：综合健康评估
- 最小参数：
```
{ "host_pattern": "production", "checks": ["system", "network", "security"], "include_recommendations": true }
```
- 示例问题：“在生产服务器上运行完整的健康检查并给出建议。”
- 示例答案： { "ok": true, "diagnosis": {...}, "health_score": {"score": 85, "level": "good"} }
可靠的捕获基线：捕获系统状态基线
- 最小参数：
```
{ "host_pattern": "web*", "snapshot_name": "pre-deployment", "include": ["configs", "processes"] }
```
- 示例问题：“部署前捕获基线快照。”
- 示例答案： { "ok": true, "snapshot_id": "snapshot_20250101_120000_abc123", "categories_captured": [...] }
可比较状态：与基线进行比较
- 最小参数：
```
{ "host_pattern": "web*", "baseline_snapshot_id": "snapshot_20250101_120000_abc123" }
```
- 示例问题：“将当前状态与部署前基线进行比较。”
- 示例答案： { "ok": true, "comparison": {"differences": {...}, "summary": {...}} }

自动化与自我修复

可自动修复：自动解决问题
- 最小参数：
```
{ "host_pattern": "database", "symptoms": ["high_memory", "disk_full"], "max_impact": "medium", "dry_run": true }
```
- 示例问题：“自动修复数据库服务器上的内存和磁盘问题（预览模式）。”
- 示例答案： { "ok": true, "proposed_actions": [...], "summary": {"actionable_symptoms": 2} }

网络与安全

可转换网络矩阵：网络连接测试
- 最小参数：
```
{ "host_patterns": ["web*", "db*"], "check_ports": [22, 3306, 443] }
```
- 示例问题：“测试web和数据库服务器之间的网络连接。”
- 示例答案： { "ok": true, "network_matrix": {...}, "summary": {"source_patterns": 2, "ports_tested": [22, 3306, 443]} }
可靠的安全审计：安全漏洞评估
- 最小参数：
```
{ "host_pattern": "all", "audit_categories": ["packages", "permissions", "network"], "generate_report": true }
```
- 示例问题：“对所有服务器进行全面的安全审计。”
- 示例答案： { "ok": true, "audit": {...}, "security_assessment": {"score": 75, "level": "warning"} }

性能与监控

可靠健康监测器：持续监测趋势
- 最小参数：
```
{ "host_pattern": "production", "monitoring_duration": 300, "metrics_interval": 30 }
```
- 示例问题：“监控生产服务器5分钟并分析趋势。”
- 示例答案： { "ok": true, "monitoring": {"trend_analysis": {...}, "anomalies": []} }
可靠的性能基准：性能基准测试
- 最小参数：
```
{ "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、内存、磁盘、网络和安全指标的自动评分
模式识别：对日志模式、错误相关性和系统异常进行智能分析
趋势检测：通过趋势分析和预测洞察进行实时监控

🔧 自动修复

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

📊 高级分析

基线比较：具有全面状态比较的时间旅行调试
性能基准测试：建立基线并检测绩效回归
安全审计：综合脆弱性评估，并进行合规评分

🛡️ 企业级安全

冲击控制：可配置的影响级别（低/中/高）和审批工作流程
审计跟踪：完整记录所有故障排除操作和决策
回滚功能：失败操作的自动恢复

🔄 纯可靠集成

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

所有故障排除工具都保持相同的安全性、可审计性和Ansible本机方法，同时提供企业级自动化功能。

法律声明

此MCP服务器是Ansible CLI工具的包装器，不包含任何Ansible源代码。

这个项目：根据EUPL 1.2许可
可理解的依赖关系：GPL v3+（Red Hat，股份有限公司）
关系：此软件通过子流程调用将Ansible作为外部工具执行，类似于调用 git 或 docker。此项目中没有复制或包含Ansible源代码。

EUPL 1.2许可证与GPL v3兼容（见EUPL附录）。

法律声明

此MCP服务器是Ansible CLI工具的包装器，不包含任何Ansible源代码。

这个项目：根据EUPL 1.2许可
可理解的依赖关系：GPL v3+（Red Hat，股份有限公司）
关系：此软件通过子流程调用将Ansible作为外部工具执行，类似于调用 git 或 docker。此项目中没有复制或包含Ansible源代码。

EUPL 1.2许可证与GPL v3兼容（见EUPL附录）。

使用说明

工具参考（详细）

故障排除套件参考

基础工具

智能诊断

自动化与自我修复

网络与安全

性能与监控

故障排除套件的主要功能

🎯 智能分析

🔧 自动修复

📊 高级分析

🛡️ 企业级安全

🔄 纯可靠集成

法律声明

法律声明

相关 MCP

Terraform Registry MCP 服务器

Microsoft 365命令行管理服务器

MCP服务器安装工具

CDK最佳实践服务

NodeMCU设备管理服务

Terraform MCP 服务器