ansible-mcp-server by caapap - MCP Server

🧩 Ansible MCP Server

一个兼容 Model Context Protocol (MCP) 的 Ansible 自动化服务器。

✨ 特性

🚀 异步执行：基于 FastAPI 的异步架构，高性能
📡 实时输出：Playbook 执行支持 SSE 流式输出
🔧 完整工具集：支持 Ad-Hoc、Playbook、Inventory 管理
🛡️ 安全加固：路径验证、超时保护、错误处理
📝 日志记录：完整的日志追踪
🐳 容器化：开箱即用的 Docker 支持

📋 支持的操作

操作	端点	说明
列出 Inventory	`/tools/list_inventory`	列出主机组和结构（JSON）
列出主机	`/tools/list_hosts`	列出所有主机
Ping 测试	`/tools/ping_hosts`	测试主机连通性
Ad-Hoc 命令	`/tools/run_ad_hoc`	执行临时命令
执行 Playbook	`/tools/run_playbook`	执行 Playbook（SSE 流）
验证 Playbook	`/tools/validate_playbook`	语法检查
生成 Playbook	`/tools/generate_playbook`	创建 Playbook 文件
获取版本	`/tools/ansible_version`	查询 Ansible 版本

🚀 快速开始

本地运行

# 1. 安装依赖
pip install -r requirements.txt

# 2. 启动服务
uvicorn main:app --reload --host 0.0.0.0 --port 8080

# 3. 访问文档
open http://localhost:8080/docs

Docker 运行

# 构建镜像
docker build -t ansible-mcp-server .

# 运行容器
docker run -d -p 8080:8080 \
  -v $(pwd)/inventory.ini:/app/inventory.ini \
  -v $(pwd)/playbooks:/app/playbooks \
  --name ansible-mcp \
  ansible-mcp-server

# 查看日志
docker logs -f ansible-mcp

Docker Compose

version: '3.8'
services:
  ansible-mcp:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - ./inventory.ini:/app/inventory.ini
      - ./playbooks:/app/playbooks
    environment:
      - ANSIBLE_HOST_KEY_CHECKING=False

📝 使用示例

1. Ping 测试所有主机

curl -X POST http://localhost:8080/tools/ping_hosts \
  -H "Content-Type: application/json" \
  -d '{"inventory": "inventory.ini"}'

2. 执行 Ad-Hoc 命令

curl -X POST http://localhost:8080/tools/run_ad_hoc \
  -H "Content-Type: application/json" \
  -d '{
    "host": "all",
    "module": "shell",
    "args": "uptime",
    "inventory": "inventory.ini"
  }'

3. 执行 Playbook（SSE 流式输出）

curl -N -X POST http://localhost:8080/tools/run_playbook \
  -H "Content-Type: application/json" \
  -d '{
    "playbook": "./site.yml",
    "inventory": "inventory.ini",
    "extra_vars": {"env": "production"}
  }'

4. 列出 Inventory

curl -X POST http://localhost:8080/tools/list_inventory \
  -H "Content-Type: application/json" \
  -d '{"inventory": "inventory.ini"}'

5. 验证 Playbook 语法

curl -X POST http://localhost:8080/tools/validate_playbook \
  -H "Content-Type: application/json" \
  -d '{"playbook": "./site.yml"}'

🔌 接入 AI 平台

Dify / Coze

在 MCP 配置中填入 SSE 端点：

http://your-host-ip:8080/sse

Cursor / Claude Desktop

在 MCP 配置文件中添加：

{
  "mcpServers": {
    "ansible": {
      "url": "http://localhost:8080/sse"
    }
  }
}

📁 目录结构

ansible-mcp-server/
├── main.py              # 入口文件
├── mcp_server.py        # MCP 服务核心逻辑
├── inventory.ini        # Ansible Inventory 配置
├── requirements.txt     # Python 依赖
├── Dockerfile          # Docker 构建文件
├── .gitignore          # Git 忽略配置
└── playbooks/          # Playbook 存放目录

🛡️ 安全注意事项

路径验证：所有文件路径都经过验证，防止路径遍历攻击
超时保护：所有命令都有超时限制
SSH 密钥：建议使用 SSH 密钥认证而非密码
网络隔离：生产环境建议部署在内网
访问控制：建议在前面加上认证网关

🔧 配置

环境变量

ANSIBLE_HOST_KEY_CHECKING: SSH 主机密钥检查（默认：False）
ANSIBLE_FORCE_COLOR: 禁用颜色输出（默认：0）
ANSIBLE_STDOUT_CALLBACK: 输出格式（默认：json）

Inventory 配置

编辑 inventory.ini 文件配置目标主机：

[webservers]
web1.example.com
web2.example.com

[databases]
db1.example.com ansible_user=admin

[all:vars]
ansible_python_interpreter=/usr/bin/python3

📊 API 文档

启动服务后访问：

Swagger UI: http://localhost:8080/docs
ReDoc: http://localhost:8080/redoc
OpenAPI Schema: http://localhost:8080/openapi.json

🐛 故障排查

1. 连接超时

# 检查主机连通性
ansible all -m ping -i inventory.ini

# 检查 SSH 配置
ssh -v user@host

2. 权限问题

# 确保有执行权限
chmod +x playbooks/*.yml

# 检查 SSH 密钥权限
chmod 600 ~/.ssh/id_rsa

3. Docker 网络问题

# 使用 host 网络模式
docker run --network host ansible-mcp-server

接入Dify/Coze（MCP Server）

在 MCP 配置中填入： http://your-host-ip:8080/sse 即可