netdev-ssh-mcp

netdev-ssh-mcp

通过 SSH 与网络设备（交换机、路由器、防火墙）交互的 MCP 服务。 支持 Arista EOS、Cisco NX-OS、Cisco IOS/IOS-XE、Juniper JunOS 和 FortiGate FortiOS。 将网络设备操作作为工具提供，以供 Claude Code / Claude Desktop / Codex （及其他 MCP 客户端）使用。

工具

get_config

从 Arista、Cisco Nexus、Cisco Catalyst、Juniper JunOS 或 FortiGate FortiOS 设备获取运行配置或启动配置。敏感值（密码、密钥、SNMP 社区名称、BGP/OSPF/TACACS/RADIUS/IKE 密钥）会自动替换为带密钥的哈希令牌：

enable secret 5 [h:3c91e0a47b2d]
snmp-server community [h:8f02d6c51e9a] ro
username admin privilege 15 secret 5 [h:3c91e0a47b2d]

在使用同一密钥时，同一个机密始终会生成相同的令牌，因此可以比较并对不同设备的配置进行差异对比——相同的令牌表示机密相同。有关如何选择密钥，请参阅混淆处理。

参数	类型	必填	默认值	说明
host	string	是	—	设备的主机名或 IP 地址
username	string	否	DEVICE_USERNAME	SSH 用户名
port	int	否	22	SSH 端口
config_type	string	否	running	running 或 startup；JunOS 或 FortiOS 不支持 startup
device_type	string	否	—	eos、ios、nxos、junos 或 fortios

FortiOS 说明：

• 使用 device_type=fortios 通过 show full-configuration 获取配置。
• fortigate 可作为 fortios 的别名。
• FortiOS 不支持 config_type=startup。

run_show_command

在网络设备上运行只读运维命令并返回输出。 对于 Arista/Cisco/JunOS，命令必须以 show 开头。对于 FortiOS，命令必须以 get 开头。在支持的情况下，追加 | json 可获取结构化输出；对于文本输出，追加 | no-more 可禁用分页。

参数	类型	必填	默认值	说明
host	string	是	—	设备的主机名或 IP 地址
command	string	是	—	要运行的只读运维命令
username	string	否	DEVICE_USERNAME	SSH 用户名
port	int	否	22	SSH 端口
device_type	string	否	—	eos、ios、nxos、junos 或 fortios

命令示例：

show bgp summary | json
show interfaces status | json
show lldp neighbors detail | json
show inventory | json
show version | json
show ip route | json
get system status
get router info routing-table all

此处不允许使用 show running-config 和 show startup-config——请改用 get_config 工具。

在 FortiOS 上，此处会阻止 show、config、execute 和 diagnose 命令。 请改用 get_config、run_ping 或 run_traceroute。

命令必须是包含单条命令的单行内容（不能包含 ;），不能使用 < 或 > 重定向，并且只能通过管道传入输出过滤器。会写入文件、发送消息或运行其他命令的过滤器（例如 save、redirect、tee 和 append）将被拒绝。允许的过滤器如下：

device_type	| 后允许的内容
eos	json、no-more、include、exclude、begin、section
ios	include、exclude、begin、section、count
nxos	ios 过滤器，以及 json、json-pretty、xml、no-more、grep、egrep、last、head
junos	display json/xml/set、no-more、match、except、count、last、find、trim
fortios	grep
未设置	eos 和 ios 过滤器的组合

过滤器模式中的 | 会被视为另一个管道，因此请使用多个过滤器，而不要使用正则表达式交替。字面量 ; 也无法发送。最接近的过滤器是正则表达式通配符 .，它可以匹配任意单个字符：| include foo.bar 可匹配 foo;bar，但也会匹配 foo-bar 或 foo bar，因此可能返回额外的行。请在模式中加入更多周围文本，以缩小匹配范围。

run_ping

在网络设备上运行 ping 命令并返回输出。 可用于从设备的角度验证可达性 — 例如，测试与 BGP 邻居、下一跳或 管理目标的连通性。

使用 device_type 选择目标平台对应的命令语法。 如果省略，则使用 EOS/IOS 语法（repeat、size 关键字）。在 FortiOS 上， 该工具会使用 execute ping-options ...，运行 execute ping，然后在 同一 SSH 会话中重置选项。

参数	类型	必填	默认值	描述
host	字符串	是	—	设备的主机名或 IP 地址
destination	字符串	是	—	要 ping 的 IP 地址或主机名
username	字符串	否	DEVICE_USERNAME	SSH 用户名
port	整数	否	22	SSH 端口
count	整数	否	—	要发送的回显请求数
timeout	整数	否	—	每次探测的超时时间（秒）；FortiOS 支持
source	字符串	否	—	源 IP 地址或接口名称
vrf	字符串	否	—	VRF 名称
size	整数	否	—	数据包大小（字节）
outgoing_interface	字符串	否	—	出接口；FortiOS 支持
device_type	字符串	否	—	eos、ios、nxos、junos 或 fortios — 控制 ping 语法

destination、source、vrf 和 outgoing_interface 只能包含 字母、数字以及 . _ : / @ % -，这些字符可用于地址、主机名和 接口名称。任何其他字符都会在联系设备前被拒绝。

FortiOS 限制：

• 此工具不支持 FortiOS 7.4+ 中的 vrf。
• FortiOS 操作输出不支持 | json。

run_traceroute

显示从设备到目标的逐跳路径及每跳延迟。 可用于定位连通性中断的位置、验证流量是否遵循预期路径，以及确定 引入延迟的跳点。

使用 device_type 确保语法正确。在 IOS 上，命令中 vrf 必须位于 目标之前 — 指定 device_type=ios 会自动处理这一点。在 FortiOS 上， 该工具会使用 execute traceroute-options ...，运行 execute traceroute，然后在 同一 SSH 会话中重置选项。

参数	类型	必填	默认值	描述
host	字符串	是	—	设备的主机名或 IP 地址
destination	字符串	是	—	要追踪到的 IP 地址或主机名
username	字符串	否	DEVICE_USERNAME	SSH 用户名
port	整数	否	22	SSH 端口
max_hops	整数	否	—	最大跳数（TTL）
timeout	整数	否	—	每次探测的超时时间（秒）
probe	整数	否	—	每跳的探测次数
source	字符串	否	—	源 IP 地址或接口名称
vrf	字符串	否	—	VRF 名称
outgoing_interface	字符串	否	—	出接口；FortiOS 支持
device_type	字符串	否	—	eos、ios、nxos、junos 或 fortios — 控制 traceroute 语法

destination、source、vrf 和 outgoing_interface 适用与 run_ping 相同的 字符限制。

FortiOS 限制：

• 此工具不支持 FortiOS 7.4+ 中的 vrf、max_hops 和 timeout。
• FortiOS 操作输出不支持 | json。

trust_host_key

获取设备当前提供的 SSH 主机密钥，并可选择将其添加到配置的 known_hosts 文件中。分两步使用：

1. 使用 confirm=false 调用，以检查当前指纹。
2. 在通过带外方式验证该指纹后，再次使用 confirm=true 调用，以将其写入 known_hosts。

如果设备主机密钥发生了合理的更改，请在验证新指纹后使用 replace_existing=true 调用。

参数	类型	必填	默认值	描述
host	string	是	—	设备的主机名或 IP 地址
port	int	否	22	SSH 端口
confirm	bool	否	false	为 false 时，仅检查当前密钥；为 true 时，将其写入
replace_existing	bool	否	false	验证后替换不匹配的现有密钥

默认用户名

设置 DEVICE_USERNAME，即可避免在每次工具调用中都指定 username：

export DEVICE_USERNAME=admin

如果提供了 username 工具参数，则该参数优先。

身份验证

身份验证方法按以下顺序尝试：

1. SSH 代理 — 如果设置了 SSH_AUTH_SOCK，则会自动使用代理。无需配置。
2. 密码 — 通过 DEVICE_PASSWORD 环境变量设置（见下文）。

调用时必须至少有一种可用的方法。

Claude Desktop 说明： Claude Desktop 是 GUI 应用，不会继承 shell 环境，因此 MCP 服务进程无法使用 SSH_AUTH_SOCK。请在配置的 env 块中显式设置该变量（见下文的 Claude Desktop 部分）。Claude Code 在终端中运行并继承 shell 环境，因此无需额外配置。

通过环境变量设置密码

在启动服务前设置 DEVICE_PASSWORD：

export DEVICE_PASSWORD=mysecret
netdev-ssh-mcp

密码绝不会通过工具参数或 MCP 协议传递 — 它会在调用时从环境中读取一次，并应用于服务进程建立的所有连接。

主机密钥验证

SSH 主机密钥验证默认启用。服务使用当前用户的 OpenSSH known_hosts 文件：

• macOS 和 Linux：~/.ssh/known_hosts
• Windows：%USERPROFILE%\\.ssh\\known_hosts

你可以通过以下任一方式覆盖路径：

• 命令行标志：--known-hosts /path/to/known_hosts
• 环境变量：SSH_KNOWN_HOSTS

如果设备不在 known_hosts 中，工具调用会失败，并显示清晰的错误，其中包含当前提供的指纹，并建议使用 trust_host_key。

若要完全禁用主机密钥验证，请使用以下任一方式：

• 命令行标志：--insecure-skip-host-key-check
• 环境变量：SKIP_HOST_KEY_CHECK=true

禁用验证是不安全的，只应作为临时的应急措施。

安装

macOS（Homebrew）

brew install --cask krisiasty/tap/netdev-ssh-mcp

二进制文件会安装到 $(brew --prefix)/bin/netdev-ssh-mcp。前缀取决于 Mac 的架构：

架构	路径
Apple 芯片（M1/M2/M3/M4）	/opt/homebrew/bin/netdev-ssh-mcp
Intel	/usr/local/bin/netdev-ssh-mcp

运行 brew --prefix，确认适用于你的机器的路径。

从源代码构建

需要 Go 1.26 或更高版本。

go build -o netdev-ssh-mcp .

构建后将二进制文件安装到 /usr/local/bin（macOS 和 Linux）：

sudo install -m 0755 netdev-ssh-mcp /usr/local/bin/

集成

在以下示例中，将 <path-to-binary> 替换为二进制文件的完整路径。如果通过 Homebrew 安装，请运行 brew --prefix 确定正确的路径（Apple 芯片为 /opt/homebrew，Intel 为 /usr/local），然后追加 /bin/netdev-ssh-mcp。

将 <path-to-key-file> 替换为混淆密钥文件的绝对路径。配置服务前请先创建该文件 — 参见混淆密钥。如果没有该文件，服务每次运行都会使用随机密钥，因此无法跨会话比较混淆后的机密。

Claude Code

在代码库根目录添加一个项目本地的 .mcp.json：

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "OBFUSCATION_KEY_FILE": "<path-to-key-file>"
      }
    }
  }
}

使用默认用户名：

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin",
        "OBFUSCATION_KEY_FILE": "<path-to-key-file>"
      }
    }
  }
}

Claude Code 在终端中运行，并继承 shell 环境，因此 SSH_AUTH_SOCK 会自动可用，无需额外配置即可通过 SSH Agent 进行身份验证。

或者，使用密码身份验证：

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "mysecret",
        "OBFUSCATION_KEY_FILE": "<path-to-key-file>"
      }
    }
  }
}

或者，使用 Claude Code CLI 全局注册该服务：

claude mcp add netdev-ssh-mcp -e OBFUSCATION_KEY_FILE=<path-to-key-file> -- <path-to-binary>

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） 或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "OBFUSCATION_KEY_FILE": "<path-to-key-file>"
      }
    }
  }
}

Claude Desktop 不会继承 shell 环境，因此必须显式设置 SSH_AUTH_SOCK。在终端中获取当前套接字路径：

echo $SSH_AUTH_SOCK

然后将其添加到配置中：

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin",
        "SSH_AUTH_SOCK": "/private/tmp/com.apple.launchd.XXXXX/Listeners",
        "OBFUSCATION_KEY_FILE": "<path-to-key-file>"
      }
    }
  }
}

请注意，每次重启后套接字路径都会改变，因此必须相应地更新配置。

或者，使用密码身份验证：

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "env": {
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "mysecret",
        "OBFUSCATION_KEY_FILE": "<path-to-key-file>"
      }
    }
  }
}

编辑配置后，重启 Claude Desktop。

示例提示词

• 显示 10.0.0.1 的运行配置
• 比较 n9k-1 和 n9k-2 的运行配置，并总结差异
• 检查 arista1 上的 BGP 邻居状态，并告知我是否有会话已断开
• 获取 10.0.0.1 的接口状态，并列出所有已关闭的接口
• 检查 10.0.0.1 的运行配置，并指出任何安全问题
• 获取 10.0.0.1 的 LLDP 邻居并绘制拓扑图
• 发往 192.168.100.0/24 的流量在 10.0.0.1 上如何转发？
• 检查 10.0.0.1、10.0.0.2 和 10.0.0.3 上的 NTP 是否一致
• 通过 LLDP/CDP 发现 spine-1 的邻居，并检查 EVPN fabric 配置
• 告诉我应使用哪些确切命令来修复你发现的配置问题
• 验证之前发现的所有问题现在是否都已修复
• 从 10.0.0.1 ping 10.0.0.2，并告诉我是否可达
• 通过逐一 ping arista1 的所有 BGP 对等体，检查 arista1 是否都能连通它们
• 从 n9k-1 的管理 VRF ping 8.8.8.8
• 从 arista1 到 10.0.0.2 执行 traceroute，并显示路径
• 从 spine-1 向它的每个 BGP 对等体执行 traceroute，并找出任何非对称路径

混淆

默认情况下，get_config 和 run_show_command 的输出中的敏感值会被混淆。run_ping 和 run_traceroute 工具不受影响——它们的输出不包含敏感值。

每个密钥都会被替换为 [h:<12 hex digits>] 形式的令牌：对密钥进行截断后的 HMAC-SHA256 值，由混淆密钥生成。没有该密钥，就无法通过猜测的值验证令牌，因此无法从输出中还原 SNMP 社区字符串等短密钥。

**混淆只能尽力而为。**系统通过匹配各受支持平台的已知配置语法来查找密钥。如果密钥出现在服务无法识别的语法中——例如新命令或很少使用的命令、特殊的平台版本或自由格式的 show 输出——则可能以明文形式出现。即使启用了混淆，也请将工具输出视为敏感信息，并在进一步分享前进行检查。如果发现未被混淆的密钥，请按照 SECURITY.md 中的说明私下报告，而不要在公开问题中报告。

混淆密钥

请提供自己的密钥。 生成一个随机密钥文件，仅需执行一次：

mkdir -p ~/.config
(umask 077 && openssl rand -hex 32 > ~/.config/netdev-ssh-mcp.key)

然后通过 --obfuscation-key-file 或 OBFUSCATION_KEY_FILE 环境变量指定该文件（如 集成 示例所示），也可以通过 OBFUSCATION_KEY 环境变量直接传入密钥。两者只能设置一个。密钥值会去除首尾空白，且长度至少为 16 字节。服务只会读取密钥，不会将其写入任何位置。

同一个密钥在每台机器上都会生成相同的令牌，因此可以共享密钥文件，以便比较在不同机器上或由不同人员收集的输出。

如果未提供密钥，服务会在每次运行时于内存中生成一个随机密钥。这是安全的——密钥不会离开进程，因此无法通过猜测的值验证令牌——但令牌只会在同一次服务运行期间匹配。较早会话、其他机器或其他人员生成的令牌无法进行比较。未配置密钥时，服务会：

• 每次启动时记录一条警告，
• 在 MCP 服务说明中告知调用它的 Agent，
• 在每个包含混淆机密的 get_config 和 run_show_command 结果后附上一条简短提示，建议配置密钥。

v1.6.6 及更早版本生成的令牌未使用密钥，因此无法与当前令牌进行比较。

禁用混淆

要禁用混淆，请传入 --no-obfuscate：

netdev-ssh-mcp --no-obfuscate

在 MCP 配置文件中，通过 args 传入：

{
  "mcpServers": {
    "netdev-ssh-mcp": {
      "command": "<path-to-binary>",
      "args": ["--no-obfuscate"]
    }
  }
}

日志记录

服务将日志写入 stderr（绝不写入 stdout，因为 stdout 专供 MCP 协议使用）。日志级别由 LOG_LEVEL 环境变量控制：

值	描述
debug	连接详情、命令字符串、字节数
info	默认值——工具调用、连接／断开、成功／失败
warn	仅警告
error	仅错误

LOG_LEVEL=debug netdev-ssh-mcp

作者

Krzysztof Ciepłucha

免责声明

此工具是在 AI 工具的协助下设计和构建的。设计决策、架构和所有代码均经过人工审查和验证。项目会在每次提交时进行自动安全检查、漏洞扫描和静态代码分析。

尽管如此，本软件仍按“原样”提供，不作任何保证。软件可能包含错误。使用风险由您自行承担。

许可证

本项目根据 Apache License, Version 2.0 获得许可。详情请参阅 LICENSE。