netdev-ssh MCP server
Commit Nov 13, 2026Allows an AI client to perform read-only operations on network devices like switches and routers via SSH.
Also known as krisiasty/netdev-ssh-mcp
- Stars
- 4
- Tools
- 20
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- Apache-2.0
What is netdev-ssh MCP?
netdev-ssh allows an AI client to perform read-only operations on network devices like switches and routers via SSH. It exposes 20 tools, such as host, username, port.
Summary generated from the project's README
About netdev-ssh MCP server
Network engineers can perform read-only inspections of switches, routers, and firewalls directly through an AI client. This server connects to hardware via SSH to execute operational commands and retrieve configurations. It supports a wide range of platforms including Arista EOS, Cisco NX-OS, Cisco IOS/IOS-XE, Juniper JunOS, FortiGate FortiOS, and Cumulus Linux 4.x.
Users can interact with devices using tools like get_config to pull running or startup settings, run_show_command to execute operational queries, and run_ping or run_traceroute for connectivity testing. The server includes an automatic platform detection feature that identifies the device type over SSH to ensure correct command syntax. To maintain security, the get_config tool automatically replaces sensitive values like passwords and SNMP community names with keyed hash tokens, allowing for safe configuration comparisons without exposing secrets.
What you can do with it
- 1Audit network configurations safelyRetrieve device configurations while automatically masking sensitive passwords and keys with hash tokens.
- 2Verify network reachabilityTest connectivity to a specific BGP peer or next-hop from the perspective of the network device.
- 3Automate platform identificationIdentify the operating system of a remote host to ensure the correct command syntax is used.
- 4Query operational device statusRun specific show commands to gather structured data about interfaces or routing tables.
Written from the project's README. Every use case is checked against a quote from it.
netdev-ssh MCP tools 20
Detected from the READMEhostusernameportconfig_typedevice_typecommandjsonno-morecountdestinationtimeoutsource
| host | — | |
| username | — | |
| port | — | |
| config_type | — | |
| device_type | — | |
| command | — | |
| json | — | |
| no-more | — | |
| count | — | |
| destination | — | |
| timeout | — | |
| source | — |
Show all 20 toolsShow fewer tools
vrfsizeoutgoing_interfacemax_hopsproberefreshconfirmreplace_existing
| vrf | — | |
| size | — | |
| outgoing_interface | — | |
| max_hops | — | |
| probe | — | |
| refresh | — | |
| confirm | — | |
| replace_existing | — |
Configuration
DEVICE_PASSWORDDEVICE_USERNAMELOG_LEVELOBFUSCATION_KEY_FILESSH_AUTH_SOCK
| Name | Description | |
|---|---|---|
| DEVICE_PASSWORD | — | |
| DEVICE_USERNAME | — | |
| LOG_LEVEL | — | |
| OBFUSCATION_KEY_FILE | — | |
| SSH_AUTH_SOCK | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablekrisiasty/netdev-ssh-mcp is public and reachablegithub.com/krisiasty/netdev-ssh-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/krisiasty/netdev-ssh-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model20 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubnetdev-ssh-mcp
MCP server for interacting with network devices (switches, routers, firewalls) over SSH. Supports Arista EOS, Cisco NX-OS, Cisco IOS/IOS-XE, Juniper JunOS, FortiGate FortiOS, and Cumulus Linux 4.x. Exposes network device operations as tools for use with Claude Code / Claude Desktop / Codex (and other MCP clients)
Platform detection
Every tool that talks to a device takes an optional device_type: eos, ios, nxos, junos, fortios or
cumulus4x (fortigate is accepted as an alias for fortios; cumulus4x has no alias).
Pass it when you know the platform, for example from an inventory system.
When device_type is omitted, the server detects the platform over SSH before running the command:
- It reads the SSH server identification string, which narrows the candidates and picks one probe command that the likely platform accepts.
- It runs that read-only probe on the same connection:
show version,get system statuswhen the server looks like a FortiGate, orcat /etc/os-releasewhen the server identifies as Debian or Ubuntu (Cumulus Linux 4.x is Debian based). - It matches platform-specific lines at the start of the probe output: the
Arista <model>line (EOS),Junos:(JunOS),Cisco Nexus Operating System(NX-OS),Cisco IOS Software/Cisco IOS XE Software(IOS), andVersion: FortiGate(FortiOS). For the os-release probe,cumulus4xneeds bothID=cumulus-linuxand aVERSION_IDstarting with4., each as a whole line (quotes around the value are accepted). Exactly one platform must match; otherwise the call fails and asks fordevice_typeinstead of guessing.
A Cumulus Linux switch whose SSH banner does not mention Debian cannot be detected; pass device_type=cumulus4x.
The result is cached per host and port for an hour, so only the first call to a host pays for the extra connection. A command that fails with a syntax error drops the cached entry, so the next call probes again. Only the start of a successful command's output is checked for a rejection message, so text later in it, such as a login banner in a configuration, is not mistaken for one.
Calls that used detection end with a note such as
device_type: junos (auto-detected over SSH). Pass device_type=junos on later calls to this host to skip detection.,
kept as a separate content block after the device output. If a command run with an explicit device_type is rejected
as invalid syntax, the result ends with a hint that the type may be wrong. Use detect_platform
to resolve a list of hosts up front.
Without device_type, run_show_command rejects a command that no supported platform accepts (for example reload
or a command joined with ;) before detection logs in to the device.
When a command fails, the error names the command and its exit status and, if the device rejected the syntax, says so.
It never includes what the device printed: that output is untrusted, can contain secrets, and would bypass the
obfuscation applied to successful output. The one exception is run_ping and run_traceroute on Cumulus Linux 4.x,
where Linux states the reason only in the output and the output holds no secrets; there it follows the exit status.
Some platforms are recognised and refused. The Cisco Business switch OS is recognised from the SSH identification
string before any command runs; Linux systems are identified by the /etc/os-release probe. Unsupported results are
not cached:
| Platform | Reason |
|---|---|
| Cumulus Linux 5.x | Not supported; 5.x is configured through NVUE rather than NCLU |
| Other Debian or Ubuntu based systems | Not supported; only Cumulus Linux 4.x is |
| Cisco Business switch OS (Catalyst 1200/1300, CBS) | Does not answer SSH exec requests |
Tools
get_config
Retrieves the running or startup configuration from an Arista, Cisco Nexus, Cisco IOS/IOS-XE, Juniper JunOS, FortiGate FortiOS, or Cumulus Linux 4.x device. Sensitive values (passwords, secrets, SNMP community names, BGP/OSPF/TACACS/RADIUS/IKE keys) are automatically replaced with keyed hash tokens:
enable secret 5 [h:3c91e0a47b2d]
snmp-server community [h:8f02d6c51e9a] ro
username admin privilege 15 secret 5 [h:3c91e0a47b2d]
Under the same key, the same secret always produces the same token, so configs from different devices can be compared and diffed — identical tokens mean identical secrets. See Obfuscation for how the key is chosen.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
host |
string | yes | — | Hostname or IP address of the device |
username |
string | no | DEVICE_USERNAME |
SSH username |
port |
int | no | 22 | SSH port |
config_type |
string | no | running |
running or startup (not on JunOS, FortiOS or Cumulus Linux) |
device_type |
string | no | detected | eos, ios, nxos, junos, fortios, or cumulus4x; see Platform detection |
Cisco IOS notes:
device_type=ioscovers any Cisco IOS or IOS-XE device — Catalyst switches, ISR/ASR routers, and others.- IOS does not support
| no-more, so the config is retrieved with plainshow running-configorshow startup-config. On EOS and NX-OS,| no-moreis appended.
FortiOS notes:
- Use
device_type=fortiosto retrieve config withshow full-configuration. fortigateis accepted as an alias forfortios.- FortiOS does not support
config_type=startup.
Cumulus Linux notes:
device_type=cumulus4xretrieves the configuration withnet show configuration commands, the NCLU command list.- Cumulus Linux has no separate startup configuration, so
config_type=startupis refused.
run_show_command
Runs operational read commands on a network device and returns the output.
For Arista/Cisco/JunOS, the command must start with show. For FortiOS, the
command must start with get. For Cumulus Linux 4.x, the command must start with net show. Append
| json for structured output where
supported, or | no-more to disable pagination for text output.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
host |
string | yes | — | Hostname or IP address of the device |
command |
string | yes | — | The operational read command to run |
username |
string | no | DEVICE_USERNAME |
SSH username |
port |
int | no | 22 | SSH port |
device_type |
string | no | detected | eos, ios, nxos, junos, fortios, or cumulus4x; see Platform detection |
Example commands:
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
net show interface json
show running-configandshow startup-config(and their abbreviations, such asshow runorshow start) are not allowed here — use theget_configtool instead. On JunOS,show configurationand its abbreviations, such asshow conf, are refused too.On FortiOS,
show,config,execute, anddiagnosecommands are blocked here. Useget_config,run_ping, orrun_tracerouteinstead.On Cumulus Linux 4.x,
net show configuration,net show commitandnet show rollback(and their abbreviations) are refused here. Useget_configinstead.
On Cumulus Linux 4.x, the command may end with json for structured output. It takes no pipes or redirection:
every word must contain only letters, digits and . _ : / , @ % and -, no word may start with -, and words are
separated by spaces. The server appends 2>&1 itself so that error messages are returned.
On the other platforms, the command must be a single line holding a single command (no ;), must start with the
verb in lower case (show, or get on FortiOS), and may not use < or > redirection. Words are separated by
spaces, and every word may contain only letters, digits and . _ : / , @ % + = ^ $ -, so quotes, brackets, braces,
globs and other shell syntax are refused. ^ and $ are there for regexes such as show ip bgp regexp ^65000_.
After | (with or without spaces around it), only the filters below are accepted, written exactly as shown, in lower
case. W is one plain word: letters, digits and . _ : / , @ % + = -, not starting with -. N is a number of up
to 6 digits. Filters can be chained, as in show interfaces status | include Ethernet | exclude down. Filters that
write files, send messages or run other commands (such as save, redirect, tee, append and JunOS find) are
refused.
Filter after | |
eos |
ios |
nxos |
junos |
fortios |
|---|---|---|---|---|---|
json |
yes | yes | |||
json-pretty, xml |
yes | ||||
no-more |
yes | yes | yes | ||
include W, exclude W, begin W, section W |
yes | yes | yes | ||
count W |
yes | ||||
count |
yes | yes | |||
grep W |
yes | yes | |||
egrep W, head, head lines N |
yes | ||||
last, last N |
yes | yes | |||
display json, display xml, display set |
yes | ||||
match W, except W, trim N |
yes |
cumulus4x takes no filters; end the command with json instead. Without device_type, the detected platform's
filters apply.
Filter arguments cannot use regular expressions beyond ., because ^, $, *, ?, brackets, braces, quotes and
backslashes are not plain-word characters; options (-v) and a second word are refused too. The device still reads
W as a regular expression, so . matches any single character: | include foo.bar matches foo;bar, but also
foo-bar or foo bar, so it can return extra lines. A | always starts a filter, even inside a regular expression
given to the command itself. When no filter fits, run the command without one (output is obfuscated either way) and
extract what you need from the full output.
run_ping
Runs a ping command on network device and returns the output. Useful for verifying reachability from the device's perspective — for example, testing connectivity to a BGP peer, next-hop, or management target.
The command syntax follows the platform (device_type, or detected). On FortiOS,
the tool uses execute ping-options ..., runs execute ping, then resets the
options within the same SSH session. On Cumulus Linux 4.x it runs Linux ping:
ping -c <count> [-s size] [-W timeout] [-I source | -I vrf] destination, with 5 probes unless count is set.
vrf=default adds no -I.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
host |
string | yes | — | Hostname or IP address of the device |
destination |
string | yes | — | IP address or hostname to ping |
username |
string | no | DEVICE_USERNAME |
SSH username |
port |
int | no | 22 | SSH port |
count |
int | no | 5 on Cumulus | Number of echo requests to send |
timeout |
int | no | — | Per-probe timeout in seconds; supported on FortiOS and Cumulus Linux |
source |
string | no | — | Source IP address or interface name |
vrf |
string | no | — | VRF name |
size |
int | no | — | Packet size in bytes |
outgoing_interface |
string | no | — | Outgoing interface; supported on FortiOS |
device_type |
string | no | detected | eos, ios, nxos, junos, fortios, cumulus4x; sets ping syntax |
destination, source, vrf and outgoing_interface may only contain
letters, digits and . _ : / @ % -, which covers addresses, hostnames and
interface names. Anything else is refused before the device is contacted.
Cumulus Linux 4.x notes:
sourceis an address or an interface, andvrfis the VRF device; both map to-I.vrfcannot be combined withsource,outgoing_interfaceis not supported, anddestination,sourceandvrfmay not start with-.- Without
vrforsource, ping runs in the default VRF: Cumulus wrapspinginvrf-wrapper.sh, which moves it out of the management VRF the SSH login runs in, and prints a line saying so. Usevrf=mgmtto ping from the management VRF. - Linux
pingexits with status 1 when nothing answered. That is a normal result here: the output, with its statistics, is returned instead of an error. Any other failure is still an error, and carries the device output.
FortiOS limitations:
vrfis not supported in this tool for FortiOS 7.4+.| jsonis not supported for FortiOS operational output.
run_traceroute
Shows the hop-by-hop path from the device to a destination and per-hop latency. Useful for locating where connectivity breaks, verifying traffic follows the expected path, and identifying which hop introduces latency.
The command syntax follows the platform (device_type, or detected). On IOS,
vrf is placed before the destination in the command. On FortiOS, the tool uses execute traceroute-options ...,
runs execute traceroute, then resets the options within the same SSH session. On Cumulus Linux 4.x it runs Linux
traceroute [--no-vrf-switch] [-m max_hops] [-w timeout] [-q probe] [-s source-ip | -i source-iface | -i vrf] destination.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
host |
string | yes | — | Hostname or IP address of the device |
destination |
string | yes | — | IP address or hostname to trace to |
username |
string | no | DEVICE_USERNAME |
SSH username |
port |
int | no | 22 | SSH port |
max_hops |
int | no | — | Maximum number of hops (TTL) |
timeout |
int | no | — | Per-probe timeout in seconds |
probe |
int | no | — | Number of probes per hop |
source |
string | no | — | Source IP address or interface name |
vrf |
string | no | — | VRF name |
outgoing_interface |
string | no | — | Outgoing interface; supported on FortiOS |
device_type |
string | no | detected | eos, ios, nxos, junos, fortios, cumulus4x; sets syntax |
The same character restrictions as run_ping apply to destination, source,
vrf and outgoing_interface.
Cumulus Linux 4.x notes:
sourcewithvrfis refused andoutgoing_interfaceis not supported, as forrun_ping.- Without
vrf, or withvrf=default, the trace runs in the default VRF:vrf-wrapper.shmoves it out of the management VRF the SSH login runs in, and prints a line saying so. vrf=mgmtbecomes--no-vrf-switch, which keeps the trace in the login's VRF. This relies on management VRF being enabled, the Cumulus default; without it, the trace runs in the default VRF.- An interface
source, and any othervrf, become-i, which binds to the device. On Cumulus 4.x that needs a root login; other users getsetsockopt SO_BINDTODEVICE: Operation not permitted. An addresssource(-s) works for any user. - A completed trace exits with status 0 even when the destination is unreachable, so any non-zero exit status is reported as an error, with the device output that states the reason.
FortiOS limitations:
vrf,max_hops, andtimeoutare not supported in this tool for FortiOS 7.4+.| jsonis not supported for FortiOS operational output.
detect_platform
Identifies a device's platform and returns the device_type to pass to the other tools, using the same probe and
cache as Platform detection. Useful before working through a list of hosts.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
host |
string | yes | — | Hostname or IP address of the device |
username |
string | no | DEVICE_USERNAME |
SSH username |
port |
int | no | 22 | SSH port |
refresh |
bool | no | false |
Ignore a cached result and probe the device again |
Example result:
device_type: junos
version: 23.4R2.13 (reported by the device)
ssh_server: SSH-2.0-OpenSSH_7.5 (reported by the device)
detected: now, over SSH
Pass device_type=junos on later calls to this host to skip detection.
trust_host_key
Fetches the SSH host key currently presented by a device and optionally adds it
to the configured known_hosts file. Use it in two steps:
- Call with
confirm=falseto inspect the current fingerprint. - After verifying that fingerprint out of band, call again with
confirm=trueto write it toknown_hosts.
If a device host key has legitimately changed, call with
replace_existing=true after verifying the new fingerprint.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
host |
string | yes | — | Hostname or IP address of the device |
port |
int | no | 22 | SSH port |
confirm |
bool | no | false |
When false, only inspect the current key; when true, write it |
replace_existing |
bool | no | false |
Replace an existing mismatched key after verification |
Default username
Set DEVICE_USERNAME to avoid specifying username in every tool call:
export DEVICE_USERNAME=admin
The username tool parameter takes precedence if provided.
Authentication
Authentication methods are tried in order:
- SSH agent — if
SSH_AUTH_SOCKis set, the agent is used automatically. No configuration needed. - Password — set via the
DEVICE_PASSWORDenvironment variable (see below).
At least one method must be available at call time.
Claude Desktop note: Claude Desktop is a GUI application and does not inherit your shell environment, so
SSH_AUTH_SOCKis not available to the MCP server process. Set it explicitly in theenvblock of the config (see the Claude Desktop section below). Claude Code runs in the terminal and inherits your shell environment, so no extra configuration is needed there.
Password via environment variable
Set DEVICE_PASSWORD before starting the server:
export DEVICE_PASSWORD=mysecret
netdev-ssh-mcp
The password is never passed through tool parameters or the MCP protocol — it is read once from the environment at call time and applies to all connections made by the server process.
Host Key Verification
SSH host key verification is enabled by default. The server uses the current
user's OpenSSH known_hosts file:
- macOS and Linux:
~/.ssh/known_hosts - Windows:
%USERPROFILE%\\.ssh\\known_hosts
You can override the path with either:
- command-line flag:
--known-hosts /path/to/known_hosts - environment variable:
SSH_KNOWN_HOSTS
If a device is not present in known_hosts, tool calls fail with a clear error
that includes the presented fingerprint and suggests using trust_host_key.
As OpenSSH does, the server first asks a device for the host key types already
stored for it in known_hosts, so a device with several host keys (for example
ECDSA and ed25519) is checked against the key you trusted rather than reported
as a mismatch. For a device with nothing stored, it prefers ed25519, then ECDSA,
then RSA, also as OpenSSH does, so that is the key trust_host_key shows.
DSA (ssh-dss) host keys are refused because they are cryptographically weak. A
device that offers only a DSA host key cannot be connected to or trusted. A DSA
key stored in known_hosts is never asked for; if the device presents another
key, it is reported as a mismatch so you can replace the stored DSA key.
To disable host key verification entirely, use either:
- command-line flag:
--insecure-skip-host-key-check - environment variable:
SKIP_HOST_KEY_CHECK=true
Disabling verification is insecure and should only be used as a temporary escape hatch.
Command timeout
Each device command may run for at most 60 seconds, counted from when the SSH session is requested. A device that accepts a command but never answers — for example one that ignores SSH exec requests — fails with a timeout error instead of blocking the tool call. Raise the limit for very large configurations with either:
- command-line flag:
--command-timeout 2m - environment variable:
SSH_COMMAND_TIMEOUT=2m
run_ping and run_traceroute wait on the network rather than the device, so they get at least 5 minutes: a
traceroute towards an unreachable destination can take minutes to give up. A longer --command-timeout applies to
them too.
The SSH handshake, including authentication, has its own 15-second limit.
If the MCP client cancels a tool call, for example because it gave up waiting, the server closes the device connection straight away, at whatever stage it has reached, instead of running on until one of these limits.
Installation
macOS (Homebrew)
brew install --cask krisiasty/tap/netdev-ssh-mcp
The binary is installed to $(brew --prefix)/bin/netdev-ssh-mcp. The prefix
depends on the Mac architecture:
| Architecture | Path |
|---|---|
| Apple Silicon (M1/M2/M3/M4) | /opt/homebrew/bin/netdev-ssh-mcp |
| Intel | /usr/local/bin/netdev-ssh-mcp |
Run brew --prefix to confirm which applies to your machine.
Build from source
Requires Go 1.26 or later.
go build -o netdev-ssh-mcp .
To install the binary to /usr/local/bin after building (macOS and Linux):
sudo install -m 0755 netdev-ssh-mcp /usr/local/bin/
Integration
In the examples below, replace <path-to-binary> with the full path to the
binary. If installed via Homebrew, run brew --prefix to determine the correct
path (/opt/homebrew on Apple Silicon, /usr/local on Intel), then append
/bin/netdev-ssh-mcp.
Replace <path-to-key-file> with the absolute path to your obfuscation key
file. Create one before configuring the server — see
Obfuscation key. Without it the server uses a random key
for each run, so obfuscated secrets cannot be compared across sessions.
Claude Code
Add a project-local .mcp.json at the root of your repository:
{
"mcpServers": {
"netdev-ssh-mcp": {
"command": "<path-to-binary>",
"env": {
"OBFUSCATION_KEY_FILE": "<path-to-key-file>"
}
}
}
}
With a default username:
{
"mcpServers": {
"netdev-ssh-mcp": {
"command": "<path-to-binary>",
"env": {
"DEVICE_USERNAME": "admin",
"OBFUSCATION_KEY_FILE": "<path-to-key-file>"
}
}
}
}
Claude Code runs in the terminal and inherits your shell environment, so
SSH_AUTH_SOCK is available automatically — no extra configuration needed for
SSH agent authentication.
Alternatively, using password authentication:
{
"mcpServers": {
"netdev-ssh-mcp": {
"command": "<path-to-binary>",
"env": {
"DEVICE_USERNAME": "admin",
"DEVICE_PASSWORD": "mysecret",
"OBFUSCATION_KEY_FILE": "<path-to-key-file>"
}
}
}
}
Alternatively, register the server globally with the Claude Code CLI:
claude mcp add netdev-ssh-mcp -e OBFUSCATION_KEY_FILE=<path-to-key-file> -- <path-to-binary>
netdev-ssh MCP questions
What tools does netdev-ssh MCP provide?
It exposes 20 tools, including host, username, port, config_type, device_type.
What network platforms are supported?
The server supports Arista EOS, Cisco NX-OS, Cisco IOS/IOS-XE, Juniper JunOS, FortiGate FortiOS, and Cumulus Linux 4.x.
How does the server handle sensitive configuration data?
Sensitive values like passwords and secrets are automatically replaced with keyed hash tokens to ensure security.
Can the server automatically detect the device type?
Yes, if the device_type is omitted, the server detects the platform over SSH by reading the identification string and running a read-only probe.