Ansible Network MCP

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虚拟环境

cd ~
python3 -m venv ~/ansible-venv
source ~/ansible-venv/bin/activate

2.安装依赖项

pip install mcp fastmcp ansible-core

3.安装Ansible集合

# 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.创建目录结构

mkdir -p ~/ansible/{inventory,group_vars,host_vars,playbooks,roles,templates,files}
mkdir -p ~/ansible-network-mcp

5.部署MCP服务器

复制 server.py 到 ~/ansible-network-mcp/ 并使其可执行：

chmod +x ~/ansible-network-mcp/server.py

6.配置克劳德桌面

编辑 ~/.config/Claude/claude_desktop_config.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. 打开克劳德桌面
2. 问：“显示我的Ansible目录结构”
3. 问：“用我的实验室设备创建一个库存文件”
4. 询问：“为我的设备组创建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.ini
• ansible_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.cfg
• ansible_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配置中的环境变量：

{
  "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:

[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:

---
# 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二进制文件：

chmod +x ~/ansible-network-mcp/server.py
chown -R $USER:$USER ~/ansible ~/ansible-venv

未找到模块

确保您在虚拟环境中使用了正确的Python：

which python
# Should show: /home/USERNAME/ansible-venv/bin/python

连接被拒绝

验证您的设备上是否启用了NETCONF或SSH：

# Test NETCONF
ssh -p 830 admin@192.168.1.1 -s netconf

# Test SSH
ssh admin@192.168.1.1

身份验证失败

检查凭据 group_vars/ 或 host_vars/:

ansible-inventory -i ~/ansible/inventory/hosts.ini --host router-01

测试服务器

手动运行服务器以检查错误：

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日志以了解连接问题：

# Linux
tail -f ~/.config/Claude/logs/mcp*.log

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

添加设备类型

思科IOS

ansible-galaxy collection install cisco.ios

创建 group_vars/cisco_routers.yml:

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

ansible-galaxy collection install arista.eos

创建 group_vars/arista_switches.yml:

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

ansible-galaxy collection install junipernetworks.junos

创建 group_vars/juniper_devices.yml:

---
ansible_network_os: junipernetworks.junos.junos
ansible_connection: netconf
ansible_port: 830
ansible_user: root
ansible_password: juniper123