MCP 服务器

ansible-mcp_python

MCP server for Ansible automation, enabling AI clients to list inventories, ping hosts, run ad-hoc commands, validate and execute playbooks, and manage playbook files via SSE.

README

🧩 Ansible MCP Server

一个完全遵循 Model Context Protocol (MCP) 标准的 Ansible 控制服务，通过 SSE 协议暴露工具接口，可接入任何支持 MCP 协议的 AI 客户端（如 Claude Desktop、Dify、Coze 等）。

工具列表

工具	说明
`list_inventory`	列出 Ansible Inventory 主机组结构（JSON）
`list_hosts`	列出 Inventory 中所有主机
`ping_hosts`	Ping 测试所有主机
`run_ad_hoc`	执行 Ansible ad-hoc 命令（模块白名单保护）
`validate_playbook`	语法检查 Playbook 文件
`run_playbook`	执行 Playbook 并返回结果
`list_playbooks`	列出 playbooks 目录下的可用文件
`generate_playbook`	生成 Playbook 文件到 playbooks 目录
`delete_playbook`	删除 playbooks 目录下的文件
`get_ansible_version`	查询 Ansible 版本信息

MCP 协议端点

端点	方法	说明
`/sse`	GET	SSE 连接入口
`/sse/messages/`	POST	发送 JSON-RPC 消息
`/health`	GET	健康检查

调用方式

MCP 工具支持两种调用格式：

方式一：标准 MCP 协议

{"method": "tools/call", "params": {"name": "list_hosts", "arguments": {}}}

方式二：直接方法名（兼容）

{"method": "list_hosts", "params": {}}

安全特性

路径越界防护：所有文件路径校验，阻止目录遍历攻击
模块白名单：ad-hoc 命令仅允许 45 个常用安全模块
超时保护：所有命令默认 60s 超时，Ping 默认 30s
异常保护：所有错误返回 JSON-RPC 标准错误响应
参数安全：所有工具参数均使用 .get() 安全访问，缺失参数返回明确错误提示

配置（环境变量）

变量	默认值	说明
`ANSIBLE_MCP_TIMEOUT`	`60`	命令超时时间（秒）
`ANSIBLE_MCP_PLAYBOOKS_DIR`	`./playbooks`	Playbook 存储目录
`ANSIBLE_MCP_INVENTORY`	`./inventory.ini`	默认 Inventory 文件路径

启动方式

使用 uv（推荐）

uv venv
uv pip install -r requirements.txt
uv run uvicorn main:app --host 0.0.0.0 --port 8080

后台运行

nohup uv run uvicorn main:app --host 0.0.0.0 --port 8080 \
  >/tmp/ansible_mcp.log 2>&1 &

Docker

docker build -t ansible-mcp .
docker run -p 8080:8080 ansible-mcp

接入 MCP 客户端

在支持 MCP 的客户端中配置 SSE 连接地址：

http://<your-server-ip>:8080/sse

客户端会自动完成以下握手流程：

连接 /sse 获取 session_id
发送 initialize 请求完成握手
调用 tools/list 自动发现工具列表
调用 tools/call 执行具体工具

项目结构

ansible-mcp_python/
├── main.py              # FastAPI 入口
├── mcp_server.py        # 核心逻辑（MCP 协议 + 工具实现 + 安全校验）
├── inventory.ini        # Ansible 清单文件
├── playbooks/           # Playbook 存储目录（gitignored）
├── requirements.txt     # Python 依赖
├── Dockerfile           # 容器构建文件
├── README.md            # 文档
└── AGENTS.md            # 贡献者指南