内容
# Netmiko MCP 服务器
> **警告：** 使用此工具可能会造成严重且极具破坏性的错误。此工具可能会导致您的环境中发生大规模中断。您及您独自一人对使用此工具负有全部责任。不要说我没有警告过您。
> 我尝试设置了合理的默认值，并限制了 Netmiko-MCP 服务器允许的内容（默认情况下）。强烈建议首先仅使用 SHOW 命令针对测试或实验室设备执行操作。您还应考虑在 LLM 和 Netmiko-MCP 之外实施额外的安全机制（例如，严格控制的 AAA 解决方案）。LLM 和 LLM 代理本质上具有很大的可变性，难以预测和控制。
<br />
## 欢迎使用 LLM 辅助的网络交互方式
netmiko-mcp 是一个模型上下文协议服务器，为您的 AI 客户端（Claude、Claude Code、Cursor、VS Code Copilot 等）提供直接、受控的访问您的网络设备的 SSH（以及 Telnet，如果绝对必要）。用纯英文提出问题；代理程序会找出要查询的设备，运行允许的命令，并以对话、格式化表格或结构化 JSON 的形式返回结果。这适应您的工作流程。
本仓库是网络工程师的起点，他们对 AI 代理在访问真实设备时能做什么感到好奇。
设置过程本身是 AI 辅助的：`skills/` 目录包含参考文件，可以直接加载到您的 AI 客户端的上下文中，以便您可以要求您的 AI 客户端帮助您配置服务器、设置库存或排除连接故障。技能应该具有相关详细信息。
<br />
## 安全建议
Netmiko-MCP 中的控制是一种尽力而为的层，不应成为您防御的唯一一道防线。您应该考虑使用 AAA（例如 TACACS+）和专用的只读服务帐户。AAA 应独立授权和审计帐户在您的设备上可以执行的命令。MCP 命令授权可能会被绕过，因此此工具仅应由授权人员使用。不应将不受信任的输入用于此 MCP。
<br />
<br />
## 什么是 MCP？
MCP（模型上下文协议）是一种用于将 AI 客户端与附加服务（在本例中为网络设备）接口的标准协议。通过将 netmiko-mcp 注册为 MCP 服务器，您的 AI 客户端可以直接连接到您的网络设备，为您的 AI 客户端提供发现库存、运行命令和返回结果的手段。所有这些都由 AI 客户端中的基于文本的提示触发。
使用 Netmiko MCP，您可以定义允许和拒绝的命令（默认情况下，所有命令都被拒绝）。Netmiko MCP 服务器在每个请求上强制执行这些限制。换句话说，您提示 LLM；LLM 通过您的 AI 客户端对 Netmiko MCP 进行工具调用，Netmiko MCP 确定命令是允许还是拒绝，然后将请求发送到网络设备（假设允许）。
## 工作原理
netmiko-mcp 位于您的 AI 客户端和网络设备之间。它支持两种传输模式：
**stdio** - 您的 AI 客户端将服务器作为本地子进程启动，并通过标准输入/输出进行通信。不打开任何端口，网络上也没有监听的端口。进程在您打开会话时启动，在您关闭会话时停止。这是单用户在自己的机器上运行服务器的最简单设置。
**可流式 HTTP** - 服务器作为独立服务运行，监听网络端口。您的 AI 客户端通过 HTTP 连接到它，而不是作为子进程启动。这允许服务器在远程主机上运行，并跨多台机器或客户端共享。它还可以在一个地方实现集中控制和审计/日志记录所有设备交互。权衡是部署稍微复杂一些（您负责启动进程并保持其运行）。
<br />
## 先决条件
- **uv** Python 包管理器，用于安装和运行服务器。有关安装说明，请在线查看详细信息。
- **支持 MCP 的 AI 客户端（例如，Claude Code、Claude Desktop、Cursor、VS Code + Copilot、Codex）**
## 安装
**选项 1 — uv 工具（推荐大多数用户）：**
```bash
uv tool install netmiko-mcp
```
**选项 2 — 从源代码克隆：**
```bash
git clone https://github.com/ktbyers/netmiko_mcp
cd netmiko_mcp
uv sync
```
> **注意：** `uv sync` 安装到项目的本地虚拟环境中，这适用于 Claude Code，但不适用于像 Claude Desktop、Cursor、Devin（前身为 Windsurf）这样的客户端，它们从不同的工作目录启动服务器。
<br />
## 入门指南
设置需要三件事：MCP 配置文件、设备库存和命令白名单。
> **最简单的设置：** 将这三个文件放在您的主目录中，使用默认名称：`~/.netmiko-mcp.yml`、`~/.netmiko.yml` 和 `~/commands.yml`。服务器会自动找到它们，无需任何环境变量或额外的客户端配置。
如果您需要使用不同的位置，请设置 `NETMIKO_MCP_CONFIG` 环境变量指向您的配置文件，该文件可以指向您的库存和命令 YML 文件的自定义位置：
```bash
export NETMIKO_MCP_CONFIG="$HOME/.netmiko-mcp.yml"
```
<br />
### 步骤 1 - 创建 Netmiko-MCP 配置文件
创建 `~/.netmiko-mcp.yml`:
```yaml
inventory_type: "netmiko_tools"
inventory_file: "~/.netmiko.yml"
command_file: "~/commands.yml"
```
有关 Netmiko-MCP 配置文件和相应环境变量的更多详细信息：[docs/configuration.md](docs/configuration.md)
<br />
<br />
### 步骤 2 - 创建设备库存
目前，设备库存仅限于 Netmiko Tools 的[设备库存](https://pynet.twb-tech.com/blog/netmiko-grep-command-line-utility.html#creating-the-inventory)。将来可能会扩展以支持其他库存源。
创建 `~/.netmiko.yml` 设备库存。该文件包含设备字典和设备组。
**凭证说明：** Netmiko Tools 库存格式要求在该文件中存储设备用户名和密码。对于实验室或测试环境，纯文本凭证完全没问题。对于其他环境，强烈建议使用内置加密选项。Netmiko 可以加密凭证字段，以便安全地存储文件而不暴露明文密码。有关 plaintext 和加密方法的详细信息，请参阅 [netmiko-tools-yml 技能](skills/netmiko-tools-yml/SKILL.md)。
Netmiko Tools AI [技能文件](https://github.com/ktbyers/netmiko_mcp/blob/main/skills/netmiko-tools-yml/SKILL.md)
<br />
<br />
### 步骤 3 - 创建命令白名单
创建 `~/commands.yml` 以定义 LLM 允许发送到设备的命令。默认情况下，**不允许任何命令：**
```yaml
allowed_commands:
- "show version"
- "show ip interface brief"
denied_commands: []
```
默认位置是 `~/commands.yml`. 要使用不同的路径，请在 `~/.netmiko-mcp.yml` 中设置 `command_file`:
```yaml
command_file: "~/network/commands.yml"
```
或使用环境变量覆盖：
```bash
export NETMIKO_MCP_COMMAND_FILE="~/network/commands.yml"
```
有关允许/拒绝匹配、通配符、管道和允许字符的完整详细信息：[docs/commands.md](docs/commands.md)
<br />
<br />
## 在您的 AI 客户端中注册
安装服务器并放置三个配置文件后，在您的 AI 客户端中注册 `netmiko-mcp`。每个客户端都有自己的配置文件或 CLI 命令来注册服务器 - 请参阅 [mcp-client-config 技能](skills/mcp-client-config/SKILL.md)，了解每个客户端的详细说明，包括 Claude Code、Claude Desktop、Cursor、Devin Desktop、VS Code + GitHub Copilot 和 Kiro。
## 支持的 MCP 客户端（2026 年 6 月）
| 客户端 | stdio | HTTP | 已验证 | 说明 |
| --- | --- | --- | --- | --- |
| Claude Code | ✓ | ✓ | ✓ | 推荐用于开发和测试 |
| Claude Desktop | ✓ | ✓ | ✓ | 代理模式；延迟工具加载 |
| Cursor | ✓ | ✓ | ✓ | 需要代理模式；使用流式 HTTP 传输（SSE 已弃用且在 Cursor 中存在已知错误） |
| Devin Desktop (formerly Windsurf) | ✓ | ✓ | ✓ | 需要代理模式（Cascade） |
| VS Code + GitHub Copilot | ✓ | ✓ | ✓ | 仅限代理模式；免费层足够 |
| Kiro (AWS IDE) | ✓ | ✓ | - | 未测试；基于文档 |
| Cline | ✓ | ✓ | - | 未测试 |
| Gemini CLI | ✓ | ✓ | - | 未测试 |
| ChatGPT | ✗ | ✗ | ✗ | 仅 SSE；需要复杂变通方法；不推荐 |
<br />
## 参考文档
| 文档 | 说明 |
| --- | --- |
| [docs/configuration.md](docs/configuration.md) | Netmiko-MCP 配置文件设置 |
| [docs/commands.md](docs/commands.md) | Netmiko-MCP 允许的命令、拒绝的命令 |
| [skills/mcp-client-config/SKILL.md](skills/mcp-client-config/SKILL.md) | 每个客户端的 MCP 配置（Claude Code、Claude Desktop、Cursor、Devin Desktop、VS Code、Kiro） |
| [skills/netmiko-tools-yml/SKILL.md](skills/netmiko-tools-yml/SKILL.md) | 设备库存格式、凭证加密、机密管理器集成 |
<br />
## 技能
`skills/` 目录包含各种技能的参考资料。
**可用技能：**
| 斜杠命令 | 加载内容 |
| --- | --- |
| `/netmiko-mcp` | 参考 `~/.netmiko-mcp.yml` 字段、命令白名单格式、管道规则，所有 7 个 MCP 工具签名 |
| `/mcp-client-config` | 为 Claude Code、Claude Desktop、Cursor、Devin Desktop、VS Code + Copilot 和 Kiro 复制粘贴 JSON 配置块，并附有每个客户端的说明 |
| `/netmiko-tools-yml` | 库存格式、逐步加密过程 |
| `/mcp-http-transport` | 何时使用 HTTP 与 stdio、SSE 与流式 HTTP、Claude.ai Web 客户端设置 |
| `/caddy-tls` | Caddy 安装、Caddyfile 示例，用于内部 CA 和 Let's Encrypt、`NODE_EXTRA_CA_CERTS` 修复、WSL2/Windows 分割主机设置 |
<br />
## MCP 工具
服务器向 MCP 客户端公开了七种工具：
| 工具 | 说明 |
| --- | --- |
| `send_show_command` | 连接到单个设备并执行显示命令。接受 `device_name`、`command` 和可选的 `use_textfsm=True` 以返回结构化 JSON 而不是原始文本。 |
| `send_show_command_to_group` | 并发执行显示命令，适用于设备组。接受 `device_or_group`、`command`，可选 `use_textfsm=True` 和可选 `save_output=True` 以写入每个设备的单独文件而不是返回原始输出。 |
| `list_devices` | 从库存中列出设备。接受可选的 `device_or_group` 参数（默认为 `"all"`）。响应中永远不会包含凭证。 |
| `list_groups` | 列出库存中定义的所有设备组名称。返回字符串列表。 |
| `list_device_outputs` | 列出设备的已保存输出文件、组或 `"all"`。返回一个字典，将设备名称映射到已保存的文件名列表（最新的排在最前面）。 |
| `read_device_output` | 读取以前保存的输出文件。接受 `device_name` 和 `filename`（由 `list_device_outputs` 返回）。 |
| `ping` | 健康检查。返回 `"pong"`。 |
## 使用示例
### 人类可读的表格输出
> **提示：** 对 Netmiko MCP 服务器配置的所有交换机执行 `show version`
LLM 通过 `list_devices` 发现设备，并并行对每个设备运行 `show version`，并将结果格式化为表格：
| 字段 | core01 | access01 |
| --- | --- | --- |
| 平台 | Arista cEOSLab | Arista cEOSLab |
| EOS 版本 | 4.35.2F（工程构建） | 4.35.2F（工程构建） |
| 架构 | x86_64 | x86_64 |
| 内核 | 5.15.0-181-generic | 5.15.0-181-generic |
| 序列号 | 34142FDC416C66E78611C8DF0D03306C | B1AFD6AA33B7A826E56244D42BBD9B8C |
| 系统 MAC | 001c.7395.64b0 | 001c.7333.16be |
| 正常运行时间 | 1d 22h 15m | 1d 22h 15m |
| 总内存 | ~16 GB | ~16 GB |
| 空闲内存 | ~12.2 GB | ~12.2 GB |
### 结构化 JSON 输出
> **提示：** 对 Netmiko MCP 服务器配置的所有交换机执行 `show version` 并以 JSON 格式返回数据。
在提示中添加“以 JSON 格式”会使 LLM 调用 `send_show_command` 并使用 `use_textfsm=True` 将原始输出解析为结构化数据：
```json
{
"core01": {
"model": "cEOSLab",
"hw_version": "",
"serial_number": "34142FDC416C66E78611C8DF0D03306C",
"sys_mac": "001c.7395.64b0",
"image": "4.35.2F-46221466.4352F",
"total_memory": "16336752",
"free_memory": "12870640",
"uptime": "1 天，22 小时和 16 分钟"
},
"access01": {
"model": "cEOSLab",
"hw_version": "",
"serial_number": "B1AFD6AA33B7A826E56244D42BBD9B8C",
"sys_mac": "001c.7333.16be",
"image": "4.35.2F-46221466.4352F",
"total_memory": "16336752",
"free_memory": "12876236",
"uptime": "1 天，22 小时和 16 分钟"
}
}
```
结构化输出在您希望将结果输送到另一个工具、编程比较字段或询问 LLM 需要字段级访问的后续问题时很有用（例如，“哪些设备的版本低于 4.34？”）。
### 将输出保存到本地文件
> **提示：** 对 Netmiko MCP 库存中的所有设备运行 `show version`，返回结构化 JSON，并将每个设备的输出保存到一个名为 `<device-name>.json` 的文件中，位于我的当前目录。
LLM 将收集所有设备的输出并写入一个文件，每个设备一个文件。明确文件名约定（`<device-name>.json`）和目标位置（`当前目录`）可以防止 LLM 猜测。
> **提示：** 如果省略目录，LLM 将根据您的 AI 客户端运行的工作目录保存文件 - 这可能与您的预期不符。如果您希望文件位于特定位置，请指定绝对路径（例如，`~/network/output/`）。
