网络 MCP 服务器

一个模型上下文协议 (MCP) 服务器，允许 AI 代理通过 SSH 与 Cisco IOS-XE 网络设备进行交互。使用 Python 构建，基于 FastMCP 和 Netmiko。

该服务器公开了 7 个工具（5 个读取 + 2 个写入），每个工具都具有严格的输入验证和清晰的描述，以便 LLM 代理能够自主发现并使用它们。

课程：Agent AI & Automation — 谢里丹学院 (Sheridan College) 作者：Ahmed 指导老师：Sebastian

实验环境

本项目针对 Cisco 的 Always-On IOS-XE DevNet Sandbox。它是免费的、公开可访问的、无需预约且始终在线。

设置	值
主机	`sandbox-iosxe-latest-1.cisco.com`
端口	`22` (SSH)
用户名	`admin`
密码	`C1sco12345`
设备类型	Cisco IOS-XE (Catalyst 8000v)

参考：Cisco DevNet — Always-On Sandboxes。

从您的机器进行快速连接检查：

ssh admin@sandbox-iosxe-latest-1.cisco.com
# password: C1sco12345

您应该会看到 Router#（或类似）提示符。如果这有效，MCP 服务器也将正常工作。

沙盒是共享的。请保持更改较小且不具破坏性（例如，仅编辑接口描述，不要关闭接口或更改 IP）。

安装

需要 Python 3.10+。

# 1. Clone / copy the project
cd network-mcp-server

# 2. Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate    # on Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

依赖项：

mcp[cli] — MCP Python SDK (提供 FastMCP)
netmiko — 多厂商 SSH/CLI 库
python-dotenv — 为本地开发加载 .env 文件

运行服务器

选项 A — 独立运行（用于本地测试）

cp .env.example .env
# edit .env if your lab uses different credentials

python server.py

服务器通过 stdio 运行，因此它会在 stdin 上等待 MCP JSON-RPC 消息。实际上，您不会手动调用它 — 您将连接 Claude Desktop（见下文）或 mcp 开发 CLI。

选项 B — 交互式开发检查器

mcp dev server.py

这会在您的浏览器中打开 MCP 检查器，您可以在其中列出工具并手动调用它们。

工具

读取工具

工具	描述
`get_device_info`	主机名、型号、软件版本、运行时间、序列号。解析 `show version`。
`get_interfaces`	所有接口的状态、IP、描述。解析 `show ip interface brief` + `show interfaces description`。
`get_routes`	IPv4 路由表。将 `show ip route` 解析为结构化条目。
`get_arp_table`	IP 到 MAC 的映射。解析 `show ip arp`。
`get_running_config`	完整的运行配置，或单个部分（例如 `interface GigabitEthernet1`）。接受可选的 `section` 参数。

写入工具

工具	描述
`configure_interface_description`	设置接口描述，并通过回读来验证更改是否已应用。参数：`interface`, `description`。
`save_config`	运行 `copy running-config startup-config` 以在重启后保留更改。

所有工具输出均为 JSON 字符串，以便 LLM 可以对结构化数据进行推理。当 Netmiko 的 TextFSM 解析器无法处理输出时，服务器会回退到 {"raw": "..."} 包装器内的原始 CLI 文本。

连接到 Claude Desktop

找到 Claude Desktop 的配置文件：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
将以下块合并到文件中（使用指向您 server.py 的完整绝对路径）：

{
  "mcpServers": {
    "network-mcp-server": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/network-mcp-server/server.py"],
      "env": {
        "DEVICE_HOST": "sandbox-iosxe-latest-1.cisco.com",
        "DEVICE_PORT": "22",
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "C1sco12345",
        "DEVICE_TYPE": "cisco_xe"
      }
    }
  }
}

可直接复制的版本位于 claude_desktop_config.example.json 中。

完全退出并重新打开 Claude Desktop。（仅关闭窗口是不够的 — 它会保持 MCP 进程处于活动状态。）
在新的聊天中，点击 🛠️ / 工具图标。您应该会看到 network-mcp-server 列出了 7 个工具。

交互示例

连接后，尝试以下提示：

“我连接的是什么设备？告诉我它的主机名、型号和 IOS 版本。” 代理将调用 get_device_info。

“列出所有当前分配了 IP 地址的接口。” 代理将调用 get_interfaces 并过滤结果。

“显示默认路由。” 代理将调用 get_routes 并选择网络为 0.0.0.0 的条目。

“将 GigabitEthernet2 的描述设置为 'managed by MCP demo'，然后确认更改已应用。” 代理将调用 configure_interface_description，然后（可选地）使用 section='interface GigabitEthernet2' 调用 get_running_config 进行二次检查。

“将运行配置保存到启动配置。” 代理将调用 save_config。

所需权限

MCP 服务器需要：

从主机到设备 SSH 端口（默认 TCP/22）的网络出口访问权限。在企业网络中，您可能需要 VPN 或代理。
具有 特权执行 (privileged exec) 权限的设备账户 — DevNet 沙盒的 admin 账户已经是 enable 级别。如果您使用自己的设备，该账户必须能够进入 config t 并执行 write memory。
对 .env 文件或 Claude Desktop 设置的等效环境变量的本地读取访问权限。

服务器不需要您工作站的 root/admin 权限。

安全说明

凭据从不硬编码。 它们来自环境变量 (DEVICE_USERNAME, DEVICE_PASSWORD)。如果缺少任何必需的环境变量，服务器将拒绝连接并返回明确的错误。
.env 已被 git 忽略。 提供了一个 .env.example（包含可安全共享的 DevNet 沙盒值）。
每个工具都有输入验证。 接口名称、描述和配置部分过滤器在到达设备 CLI 之前都会经过正则表达式验证。Shell 元字符（;, |, 反引号, 换行符, 空字节）会被拒绝。
凭据从不作为工具参数公开。 LLM 无法读取、记录或泄露它们 — 它只能看到工具输出。
写入工具包含验证。 configure_interface_description 在应用更改后会回读配置并报告 applied: true/false。
范围狭窄。 两个写入工具只能更改接口描述并保存配置。破坏性操作（关闭接口、更改 IP 地址、删除 VLAN、erase startup-config）被刻意排除在外。

故障排除

“缺少必需的环境变量” 您忘记设置 DEVICE_HOST / DEVICE_USERNAME / DEVICE_PASSWORD。将 .env.example 复制到 .env 或在 Claude Desktop 的 env 块中设置它们。

“到 的身份验证失败” 仔细检查密码。如果您更改了沙盒或使用了不同的设备，请确保启用了 SSH 并且该账户具有特权执行权限。

“到 的连接超时” 网络出口被阻止。尝试从同一台机器运行 ssh admin@sandbox-iosxe-latest-1.cisco.com。如果这也挂起，则说明是您的防火墙/VPN 的问题。

编辑配置后 Claude Desktop 未显示服务器 完全退出 Claude Desktop（不仅仅是关闭窗口）并重新打开它。在 macOS 上：Cmd+Q。在 Windows 上：右键点击托盘图标 → 退出。

工具调用返回原始文本而不是解析后的 JSON 这意味着 Netmiko 的 TextFSM 模板与设备输出不匹配（不同的 IOS 版本、不同的平台）。服务器会回退到 {"raw": "..."} 中的原始 CLI 文本。代理仍然可以对其进行推理；只是它不是结构化的。

Network MCP Server