Ansible网络MCP服务器
一种模型上下文协议(MCP)服务器,使Claude Desktop能够管理Ansible环境并在网络设备上执行网络自动化任务。
概述
Ansible Network MCP Server连接了会话式人工智能和网络基础设施管理。它允许网络工程师用自然语言描述自动化目标,并让Claude通过Ansible执行这些目标。
特性
目录和文件管理
- 浏览完整的Ansible目录结构
- 读取和写入Ansible工作区中的任何文件
- 修改前自动备份文件
库存管理
- 读取和更新库存文件
- 动态添加或删除主机
- 列出所有主机和组
变量管理
- 管理group_vars和host_vars文件
- 读取和写入YAML变量文件
- 查看任何主机的计算变量
配置管理
- 阅读并更新ansible.cfg
- 配置连接设置
- 设置超时和其他参数
剧本操作
- 根据描述创建新的剧本
- 编辑现有剧本
- 验证剧本语法
- 运行带有各种选项的剧本
- 执行模拟运行检查
设备交互
- 使用ping测试连接
- 收集设备事实
- 检索正在运行的配置
- 执行显示命令
- 推送配置更改
模板管理
- 创建和管理Jinja2模板
- 列出可用模板
- 读取模板内容
先决条件
- Linux系统(Ubuntu 24.04或类似版本)
- Python 3.10或更高版本
- Claude桌面应用程序
- 具有NETCONF或SSH访问权限的网络设备
- 与目标设备的网络连接
安装
1.创建Python虚拟环境```bash
cd ~
python3 -m venv ~/ansible-venv
source ~/ansible-venv/bin/activate
### 2.安装依赖项```bash
pip install mcp fastmcp ansible-core
3.安装Ansible集合```bash
For Juniper devices
ansible-galaxy collection install junipernetworks.junos
For Cisco devices
ansible-galaxy collection install cisco.ios cisco.nxos
For Arista devices
ansible-galaxy collection install arista.eos
### 4.创建目录结构```bash
mkdir -p ~/ansible/{inventory,group_vars,host_vars,playbooks,roles,templates,files}
mkdir -p ~/ansible-network-mcp
5.部署MCP服务器
复制 server.py 到 ~/ansible-network-mcp/ 并使其可执行:```bash
chmod +x ~/ansible-network-mcp/server.py
### 6.配置克劳德桌面
编辑 `~/.config/Claude/claude_desktop_config.json`:```json
{
"mcpServers": {
"ansible-network-mcp": {
"command": "/home/USERNAME/ansible-venv/bin/python",
"args": ["/home/USERNAME/ansible-network-mcp/server.py"],
"env": {
"ANSIBLE_HOST_KEY_CHECKING": "False",
"ANSIBLE_FORCE_COLOR": "false"
}
}
}
}
替换 USERNAME 使用您的实际用户名。
7.重新启动克劳德桌面
完全退出并重新启动Claude Desktop以加载MCP服务器。
目录结构
安装后:```
~/ansible/
├── ansible.cfg
├── inventory/
│ └── hosts.ini
├── group_vars/
│ └── switches.yml
├── host_vars/
├── playbooks/
├── roles/
├── templates/
└── files/
## 快速开始
### 初始设置
1. 打开克劳德桌面
1. 问:“显示我的Ansible目录结构”
1. 问:“用我的实验室设备创建一个库存文件”
1. 询问:“为我的设备组创建group_vars”
### 示例工作流
**备份设备配置:**```
You: Create a playbook that backs up all device configs
Claude: [creates backup_configs.yml playbook]
You: Run it in check mode first
Claude: [executes dry-run]
You: Looks good, run it for real
Claude: [executes playbook]
配置OSPF:```
You: Create a playbook to configure OSPF area 0 on all routers
Claude: [creates ospf_config.yml playbook]
You: Test it on router-01 only
Claude: [runs with --limit router-01]
**连接故障排除:**```
You: Ping all my devices
Claude: [runs ansible ping module]
You: Why is router-02 unreachable?
Claude: [analyzes and suggests fixes]
用法示例
管理库存
- “显示我当前的库存”
- “将名为router-03、IP为192.168.1.3的新主机添加到路由器组”
- “从库存中删除旧交换机”
- “列出core_switch组中的所有主机”
使用变量
- “显示路由器的group_vars”
- “使用NETCONF设置为core_switch创建group_vars”
- “router-01的有效变量是什么?”
- “更新group_vars/all.yml中的ansible_user”
创建播放手册
- “创建一个在所有设备上设置主机名的剧本”
- “创建配置NTP服务器的剧本”
- “创建一个收集界面统计信息的剧本”
运行播放簿
- “运行备份剧本”
- “仅在路由器组上运行ntp_config.yml”
- “检查ospf剧本会做出哪些更改”
- “验证我的备份剧本的语法”
设备操作
- “从所有交换机获取运行配置”
- “在router-01上运行‘显示版本’”
- “将此配置推送到交换机-01:设置系统名称服务器8.8.8.8”
- “从所有设备收集事实”
可用工具
服务器提供30多种按功能组织的工具:
结构管理
ansible_show_structure-显示目录树ansible_read_file-读取任何文件ansible_write_file-写入/创建文件
库存
ansible_read_inventory-查看hosts.iniansible_write_inventory-更新库存ansible_add_host-添加新主机ansible_remove_host-删除主机ansible_list_inventory-列出主机和组
变量
ansible_list_vars-列出所有var文件ansible_read_group_vars-读取组变量ansible_write_group_vars-更新组变量ansible_read_host_vars-读取主机变量ansible_write_host_vars-更新主机变量ansible_show_host_vars-显示计算变量
配置
ansible_read_config-阅读ansible.cfgansible_write_config-更新ansible.cfg
剧本
ansible_list_playbooks-列出所有剧本ansible_create_playbook-创建新剧本ansible_read_playbook-查看剧本ansible_edit_playbook-更新剧本ansible_delete_playbook-删除剧本ansible_validate_playbook-检查语法ansible_run_playbook-执行剧本ansible_check_playbook-预演剧本
设备操作
ansible_ping_devices-测试连接性ansible_get_facts-收集设备事实ansible_get_config-获取运行配置ansible_run_command-执行显示命令ansible_push_config-推送配置ansible_adhoc_command-运行任何Ansible模块
模板
ansible_list_templates-列出模板ansible_read_template-查看模板ansible_create_template-创建模板
配置
Ansible目录位置
默认情况下,服务器使用 ~/ansible。要使用其他位置,请设置 ANSIBLE_DIR Claude Desktop配置中的环境变量:```json
{
"mcpServers": {
"ansible-network-mcp": {
"command": "/home/USERNAME/ansible-venv/bin/python",
"args": ["/home/USERNAME/ansible-network-mcp/server.py"],
"env": {
"ANSIBLE_DIR": "/custom/path/to/ansible",
"ANSIBLE_HOST_KEY_CHECKING": "False"
}
}
}
}
### 库存示例
样品 `inventory/hosts.ini`:```ini
[routers]
router-01 ansible_host=192.168.1.1
router-02 ansible_host=192.168.1.2
[switches]
switch-01 ansible_host=192.168.1.10
switch-02 ansible_host=192.168.1.11
组变量示例
样品 group_vars/routers.yml:```yaml
Connection settings
ansible_network_os: cisco.ios.ios
ansible_connection: network_cli
ansible_user: admin
ansible_password: secret123
ansible_become: yes
ansible_become_method: enable
Common settings
ntp_servers:
- 10.0.0.1
- 10.0.0.2
## 安全
MCP服务器实施了多种安全措施:
- **路径限制:** 所有文件操作仅限于Ansible目录
- **输入消毒:** 用户输入经过消毒,以防止命令注入
- **自动备份:** 文件在修改前已备份
- **密码屏蔽:** 凭据在输出中被屏蔽
- **没有SSH密钥访问:** 服务器不直接访问SSH密钥
**最佳实践:**
- 对敏感凭据使用Ansible Vault
- 限制Ansible目录上的文件权限
- 在专用用户帐户下运行服务器
- 执行前查看剧本
- 使用检查模式进行验证
## 故障排除
### 拒绝许可(EACCES)
如果Claude Desktop无法执行Python二进制文件:```bash
chmod +x ~/ansible-network-mcp/server.py
chown -R $USER:$USER ~/ansible ~/ansible-venv
未找到模块
确保您在虚拟环境中使用了正确的Python:```bash
which python
Should show: /home/USERNAME/ansible-venv/bin/python
### 连接被拒绝
验证您的设备上是否启用了NETCONF或SSH:```bash
# Test NETCONF
ssh -p 830 admin@192.168.1.1 -s netconf
# Test SSH
ssh admin@192.168.1.1
身份验证失败
检查凭据 group_vars/ 或 host_vars/:```bash
ansible-inventory -i ~/ansible/inventory/hosts.ini --host router-01
### 测试服务器
手动运行服务器以检查错误:```bash
source ~/ansible-venv/bin/activate
python ~/ansible-network-mcp/server.py
预期产量:```
Starting Ansible Network MCP Server...
Ansible directory: /home/username/ansible
Inventory: /home/username/ansible/inventory/hosts.ini
Playbooks: /home/username/ansible/playbooks
### 克劳德桌面日志
检查Claude Desktop日志以了解连接问题:```bash
# Linux
tail -f ~/.config/Claude/logs/mcp*.log
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
添加设备类型
思科IOS```bash
ansible-galaxy collection install cisco.ios
创建 `group_vars/cisco_routers.yml`:```yaml
---
ansible_network_os: cisco.ios.ios
ansible_connection: network_cli
ansible_user: admin
ansible_password: cisco123
ansible_become: yes
ansible_become_method: enable
Arista EOS```bash
ansible-galaxy collection install arista.eos
创建 `group_vars/arista_switches.yml`:```yaml
---
ansible_network_os: arista.eos.eos
ansible_connection: network_cli
ansible_user: admin
ansible_password: arista123
ansible_become: yes
ansible_become_method: enable
Juniper JunOS```bash
ansible-galaxy collection install junipernetworks.junos
创建 `group_vars/juniper_devices.yml`:```yaml
---
ansible_network_os: junipernetworks.junos.junos
ansible_connection: netconf
ansible_port: 830
ansible_user: root
ansible_password: juniper123
