gnmi-mcp-server
Provides gNMI-based management of Nokia SR OS network devices (validated against the SR OS state tree), exposing tools for capability discovery, retrieving state/configuration paths, setting configuration, and streaming telemetry subscriptions from routers.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
gnmi-mcp-server
Go MCP server for gNMI network device management — built on gnmic's Go API.
gnmi-mcp-server exposes gNMI device operations to AI assistants (Claude Code, Codex, OpenCode) via the Model Context Protocol. It is a single statically linked binary with no runtime dependencies.
Tested devices: validated against Arista EOS (gNMI; OpenConfig + eos_native) and Nokia SR OS (state tree). Other gNMI / OpenConfig platforms should work but are untested — paths and behavior vary by vendor; use
gnmi_capabilitiesto confirm what a device supports.
Install
One-line install (macOS / Linux) — downloads the right binary into /usr/local/bin:
curl -fsSL https://raw.githubusercontent.com/Howthemeaning/gnmi-mcp-server/main/install.sh | shInstall without sudo: curl -fsSL .../install.sh | INSTALL_DIR="$HOME/.local/bin" sh (the variable must be set on sh, not curl; make sure that directory is on your PATH).
Manual: grab your platform's archive from the Releases page, extract it, and put gnmi-mcp-server on your PATH:
Platform | Asset |
Linux x86_64 |
|
Linux ARM64 |
|
macOS Intel |
|
macOS Apple Silicon |
|
macOS Gatekeeper: a binary downloaded through the browser from the Releases page is quarantined and may be blocked on first run ("cannot verify the developer"). Clear it once before use:
xattr -d com.apple.quarantine ./gnmi-mcp-server. (Thecurl … | shinstaller is not affected —curldoes not set the quarantine flag.)
From source (needs Go 1.25+):
go install github.com/Howthemeaning/gnmi-mcp-server@latestDocker: every release publishes an image to GHCR.
docker run -i --rm \
-v $HOME/.gnmi-mcp-server/config.yaml:/config.yaml:ro \
-e GNMI_PASS_CORE_SWITCH \
ghcr.io/howthemeaning/gnmi-mcp-server:latest --config /config.yamlMCP uses stdin/stdout for stdio transport, so
-i(interactive) is required. Always pass the mounted config with--config: the image is builtFROM scratchwith no user database, so the home-directory default path is not reliable inside the container. Forward any${VAR}credentials with-e. To build the image yourself:docker build -t gnmi-mcp-server ..
For AI agents (one-shot)
An agent can install, seed a config, and register the server in one block (macOS / Linux):
# 1. install the binary onto your PATH
curl -fsSL https://raw.githubusercontent.com/Howthemeaning/gnmi-mcp-server/main/install.sh | sh
# 2. seed a config, then edit devices + credentials
mkdir -p ~/.gnmi-mcp-server
curl -fsSL https://raw.githubusercontent.com/Howthemeaning/gnmi-mcp-server/main/gnmi-mcp.example.yaml \
-o ~/.gnmi-mcp-server/config.yaml
# 3. auto-register with every detected client (Claude Code / Codex / OpenCode)
gnmi-mcp-server installgnmi-mcp-server install detects each client and wires it up — Claude Code and Codex via their mcp add CLIs, OpenCode by merging opencode.json (idempotent; skips clients it can't find). Pass --config /abs/path.yaml to bake a specific config path into the registration.
Related MCP server: Cisco NSO MCP Server
Updating
gnmi-mcp-server updateDownloads the latest release, verifies its SHA256 checksum, and atomically replaces the binary in place — then restart your MCP client. (Re-running curl … install.sh | sh or go install …@latest also updates.) On startup the server checks at most once per day and logs a note to its log file when a newer version is available; it never updates silently.
If the binary lives in a root-owned directory (e.g.
/usr/local/bin), runsudo gnmi-mcp-server update. Installing to~/.local/binavoids sudo.Binaries built with
go installreport versiondevand cannot self-update — re-rungo install …@latestinstead. For Docker, pull the new image tag.
Configuration
Copy the template and edit it for your devices:
cp gnmi-mcp.example.yaml ~/.gnmi-mcp-server/config.yaml
chmod 600 ~/.gnmi-mcp-server/config.yaml # if you keep credentials inlinegnmi-mcp.example.yaml (in this repo) documents every field. A minimal config looks like this. Passwords may be literals or ${ENV_VAR} / ${ENV_VAR:-default} references — the server interpolates them at startup so credentials never appear in the MCP tool arguments.
devices:
core-switch:
address: 192.168.1.1:57400
username: admin
password: ${GNMI_PASS_CORE_SWITCH} # env-var interpolation
skip-verify: true # skip TLS cert verification
leaf-01:
address: 10.0.0.1:57400
username: operator
password: ${GNMI_PASS_LEAF_01}
timeout: 30s # default: 30s
# Optional global settings
read-only: false # set true to disable gnmi_set
# allow-arbitrary: false # set true to allow ad-hoc host:port targets
# yang-dir: ~/yang # enables gnmi_path tool
# data-dir: ~/.gnmi-mcp-server/data
# log-level: info # debug / info / warn / errorWhere to put the config
The server looks for its config in this order (first match wins):
--config <path>flagGNMI_CONFIG=<path>environment variable./gnmi-mcp.yamlin the current working directory~/.gnmi-mcp-server/config.yaml(home default)
Two recommended setups:
Zero-arg (simplest): put your config at
~/.gnmi-mcp-server/config.yaml, then launch with justgnmi-mcp-server— no--configneeded.Explicit (portable): put the config anywhere and pass
--config /abs/path/gnmi-mcp.yaml.
When the server is launched by an MCP client (opencode / Claude Code), the working directory is unpredictable — do not rely on
./gnmi-mcp.yaml. Use the home default or an absolute--configpath.
Start the server manually to test:
gnmi-mcp-server --config /path/to/gnmi-mcp.yaml
# or, with ~/.gnmi-mcp-server/config.yaml in place:
gnmi-mcp-serverTLS
To use mutual TLS, add tls-ca, tls-cert, and tls-key under a device. Set tls-dir at the top level to restrict certificate paths to a safe directory:
tls-dir: /etc/gnmi-certs
devices:
secure-router:
address: 10.1.0.1:57400
username: admin
password: ${ROUTER_PASS}
tls-ca: ca.pem # relative to tls-dir
tls-cert: client.pem
tls-key: client.keyinsecure (plaintext gRPC) and skip-verify (TLS without certificate verification) are per-device settings in the config; tool calls cannot turn them on for a configured device (see Safety).
Logs and session data
Everything the server writes lives under data-dir (default ~/.gnmi-mcp-server/data):
Path | Contents |
| Server log, rotated by |
| STREAM telemetry, one notification per line (rotated the same way). |
| Latest stream error, including transient ones the server reconnected from. |
STREAM sessions stop when the server exits. On the next start, sessions left running are marked ended, and finished sessions older than 7 days are deleted.
Troubleshooting: "environment variable referenced in config is not set"
The server no longer exits on config errors: it starts in degraded mode and reports this error through every tool call and the MCP instructions, so you will see it inside your MCP client rather than as a silent crash.
This error usually means you launched the server from a macOS GUI app (e.g. Claude Code.app). macOS GUI apps inherit their environment from launchd, not from ~/.zshrc or ~/.bash_profile — they never see shell-exported variables.
Two fixes, in order of simplicity:
Option A — set the variable in your MCP client's env block — env for Claude Code and Codex, environment for OpenCode. See Supported clients for each client's syntax.
Option B — replace ${VAR} with plaintext in config.yaml.
Supported clients
gnmi-mcp-server is a standard stdio MCP server, so any MCP client can run it. The three clients below are supported explicitly. With the binary on your PATH and the config at ~/.gnmi-mcp-server/config.yaml, the launch command is just gnmi-mcp-server; add --config /abs/path.yaml only if the config lives elsewhere.
Client |
| Where the server is registered | Env block for |
Yes, via |
|
| |
Yes, via |
|
| |
Yes, merges the JSON |
|
|
A tool call can take up to about twice the device timeout (default 30s), because gnmi_get retries once on a timeout. Make sure the client's tool timeout allows for that; the notes below say where.
Claude Code
claude mcp add -s user gnmi -- gnmi-mcp-server
# with a credential variable (keep another option between -e and the server name):
claude mcp add -e GNMI_PASS_CORE_SWITCH=... -s user gnmi -- gnmi-mcp-serverOr edit ~/.claude.json:
{ "mcpServers": { "gnmi": { "command": "gnmi-mcp-server", "env": { "GNMI_PASS_CORE_SWITCH": "..." } } } }Tools appear as
mcp__gnmi__gnmi_getetc.; prompts as/mcp__gnmi__device_health.Claude Code caps MCP tool output at 25,000 tokens by default, and a full 128 KiB
gnmi_getresponse can exceed that. Launch it withMAX_MCP_OUTPUT_TOKENS=50000, or have the model pass a smallermax_bytes.
Codex
codex mcp add gnmi --env GNMI_PASS_CORE_SWITCH=... -- gnmi-mcp-serverOr edit ~/.codex/config.toml:
[mcp_servers.gnmi]
command = "gnmi-mcp-server"
# args = ["--config", "/abs/path/gnmi-mcp.yaml"]
env_vars = ["GNMI_PASS_CORE_SWITCH"] # forward from your shell, or set values under [mcp_servers.gnmi.env]
tool_timeout_sec = 120 # default is 60Codex gives each tool call 60 s by default, which a slow device plus one retry can exceed — raise
tool_timeout_sec.Pass credentials with the
envtable, or list the variables to forward from your shell inenv_vars.
OpenCode
Edit ~/.config/opencode/opencode.json:
{
"mcp": {
"gnmi": {
"type": "local",
"command": ["gnmi-mcp-server"],
"enabled": true,
"environment": { "GNMI_PASS_CORE_SWITCH": "{env:GNMI_PASS_CORE_SWITCH}" },
"timeout": 120000
}
}
}The env key is
environment, notenv;{env:VAR}reads the variable from the shell that launched OpenCode.timeout(milliseconds) also bounds tool calls; raise it for slow devices.Tools are prefixed with the server name (
gnmi_gnmi_get, …);"tools": { "gnmi_*": false }disables them all.gnmi-mcp-server installonly edits an existing~/.config/opencode/opencode.json; if that file has comments (JSONC), it prints manual instructions instead.
Tools
Tool | gNMI RPC | Description |
| — | List the devices configured on this server (target names + addresses). |
| Capabilities | Query supported gNMI version, YANG models, and encodings. Results are cached for 5 minutes. |
| Get | Read configuration or state data from a device. Supports path, prefix, type (CONFIG/STATE/OPERATIONAL/ALL) and encoding. |
| Set | Two-phase config write: first call returns a dry-run preview and a |
| Subscribe | ONCE returns a telemetry snapshot synchronously; STREAM starts a background session (manage via |
| — | List all subscribe sessions and their current status. |
| — | Stop a running subscribe session. |
| — | Read the last |
| — | List available YANG modules under the configured |
The device tools (gnmi_capabilities, gnmi_get, gnmi_set, gnmi_subscribe) take a target — a device name from gnmi_targets — or, when allow-arbitrary is enabled, a raw address (host:port). They also accept optional connection overrides: insecure, skip_verify, and tls_ca / tls_cert / tls_key (see Safety).
To keep responses small, gnmi_get, gnmi_capabilities and ONCE subscriptions cap output with max_bytes (default 128 KiB), and gnmi_get takes max_notifications to keep only the first N notifications of a broad path.
Prompts
Guided templates (MCP prompts) that expand into ready-to-run requests; each takes a target:
device_health— uptime + interface errors + BGP state summaryinterface_errors— interfaces with non-zero errors/discardsbgp_status— BGP neighbors and session state
Safety
Writes and credentials are guarded by the server itself, not left to the model:
Read-only mode —
read-only: trueremovesgnmi_setentirely.Two-phase writes —
gnmi_setapplies only with a single-useconfirm_tokenfrom a dry-run of the same target, connection settings and operations; tokens expire after 10 minutes. The dry-run is a local preview: it does not contact the device.Credentials stay in the config — usernames and passwords are never tool arguments; use
${ENV}references to keep them out of the file too.No TLS downgrades from tool calls — for a configured target, tool arguments may make the transport stricter but cannot set
insecureorskip_verifytotrue.Ad-hoc addresses are opt-in —
addressis rejected unlessallow-arbitrary: true, and such connections carry no credentials.TLS file paths are confined — with
tls-dirset, certificate paths from the config or tool arguments must resolve inside it (symlinks included); without it, tool arguments cannot supply TLS paths at all.
Example Interaction
> What YANG models does core-switch support?
AI calls gnmi_capabilities(target="core-switch")
> Read the system state (hostname, boot time) from core-switch
AI calls gnmi_get(target="core-switch", path="/system/state")
> Rename core-switch hostname to dc1-core
AI calls gnmi_set(target="core-switch", operations=[{"op":"update","path":"/system/config/hostname","value":"\"dc1-core\""}])
→ returns dry-run preview + confirm_token
AI calls gnmi_set(target="core-switch", operations=[...same...], confirm="<token>")
→ applied
> Stream interface counters from core-switch, sampled every 10s
AI calls gnmi_subscribe(target="core-switch", path="/interfaces/interface/state/counters",
mode="STREAM", stream_mode="SAMPLE", sample_interval="10s",
session_name="counters-stream")
> Show latest telemetry
AI calls gnmi_session_tail(session_name="counters-stream")License
MIT License — use, modify, and distribute freely.
Built with gnmic · MCP Go SDK
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
AI helper for choosing and speccing network & security products from Cisco, Arista, Juniper and more
AI network lab: build and validate real multi-vendor router and switch labs from a prompt.
Network hardware BOMs, built inside your AI assistant
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn open-source network operations integration platform that connects large language models with network devices through the Model Context Protocol, allowing AI assistants to perform network configuration, diagnostics, and management tasks.9-
- AlicenseBqualityDmaintenanceEnables AI-powered network automation through natural language interactions with Cisco NSO, providing access to device management, configuration retrieval, sync operations, and service orchestration via the RESTCONF API.94MIT
- AlicenseNot gradedqualityDmaintenanceProvides AI assistants with direct access to multi-vendor network devices for tasks like configuration management, health checks, and topology discovery through 35 specialized tools. It enables natural language control over platforms including Cisco, Juniper, and Nokia using SSH, NETCONF, and SNMP protocols.12MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to execute SSH commands on network devices using natural language, supporting multiple vendors and authentication methods for automated network management.GPL 3.0