Skip to main content
Glama

gnmi-mcp-server

CI Go 1.25+ License MIT

English | 简体中文

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_capabilities to 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 | sh

Install 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

gnmi-mcp-server_linux_amd64.tar.gz

Linux ARM64

gnmi-mcp-server_linux_arm64.tar.gz

macOS Intel

gnmi-mcp-server_darwin_amd64.tar.gz

macOS Apple Silicon

gnmi-mcp-server_darwin_arm64.tar.gz

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. (The curl … | sh installer is not affected — curl does not set the quarantine flag.)

From source (needs Go 1.25+):

go install github.com/Howthemeaning/gnmi-mcp-server@latest

Docker: 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.yaml

MCP uses stdin/stdout for stdio transport, so -i (interactive) is required. Always pass the mounted config with --config: the image is built FROM scratch with 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 install

gnmi-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 update

Downloads 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), run sudo gnmi-mcp-server update. Installing to ~/.local/bin avoids sudo.

Binaries built with go install report version dev and cannot self-update — re-run go install …@latest instead. 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 inline

gnmi-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 / error

Where to put the config

The server looks for its config in this order (first match wins):

  1. --config <path> flag

  2. GNMI_CONFIG=<path> environment variable

  3. ./gnmi-mcp.yaml in the current working directory

  4. ~/.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 just gnmi-mcp-server — no --config needed.

  • 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 --config path.

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-server

TLS

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.key

insecure (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

logs/gnmi-mcp-server.log

Server log, rotated by log-max-size / log-backup-count. Check here first when a tool misbehaves.

sessions/<name>/output.jsonl

STREAM telemetry, one notification per line (rotated the same way).

sessions/<name>/err.log

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

gnmi-mcp-server install

Where the server is registered

Env block for ${VAR} credentials

Claude Code

Yes, via claude mcp add -s user

~/.claude.json (or project .mcp.json)

env / -e KEY=value

Codex

Yes, via codex mcp add

~/.codex/config.toml

env table or env_vars

OpenCode

Yes, merges the JSON

~/.config/opencode/opencode.json

environment

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-server

Or edit ~/.claude.json:

{ "mcpServers": { "gnmi": { "command": "gnmi-mcp-server", "env": { "GNMI_PASS_CORE_SWITCH": "..." } } } }
  • Tools appear as mcp__gnmi__gnmi_get etc.; prompts as /mcp__gnmi__device_health.

  • Claude Code caps MCP tool output at 25,000 tokens by default, and a full 128 KiB gnmi_get response can exceed that. Launch it with MAX_MCP_OUTPUT_TOKENS=50000, or have the model pass a smaller max_bytes.

Codex

codex mcp add gnmi --env GNMI_PASS_CORE_SWITCH=... -- gnmi-mcp-server

Or 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 60
  • Codex 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 env table, or list the variables to forward from your shell in env_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, not env; {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 install only edits an existing ~/.config/opencode/opencode.json; if that file has comments (JSONC), it prints manual instructions instead.

Tools

Tool

gNMI RPC

Description

gnmi_targets

—

List the devices configured on this server (target names + addresses).

gnmi_capabilities

Capabilities

Query supported gNMI version, YANG models, and encodings. Results are cached for 5 minutes.

gnmi_get

Get

Read configuration or state data from a device. Supports path, prefix, type (CONFIG/STATE/OPERATIONAL/ALL) and encoding.

gnmi_set

Set

Two-phase config write: first call returns a dry-run preview and a confirm_token; call again with the same target, operations and confirm=<token> to apply. Token is single-use and expires in 10 minutes. Disabled when read-only: true.

gnmi_subscribe

Subscribe

ONCE returns a telemetry snapshot synchronously; STREAM starts a background session (manage via gnmi_session_*) that reconnects automatically after transient errors. POLL is not supported — use STREAM or ONCE.

gnmi_session_list

—

List all subscribe sessions and their current status.

gnmi_session_stop

—

Stop a running subscribe session.

gnmi_session_tail

—

Read the last lines (default 20, max 500) of a session's output as JSONL.

gnmi_path

—

List available YANG modules under the configured yang-dir (only registered when yang-dir is set).

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 summary

  • interface_errors — interfaces with non-zero errors/discards

  • bgp_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: true removes gnmi_set entirely.

  • Two-phase writes — gnmi_set applies only with a single-use confirm_token from 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 insecure or skip_verify to true.

  • Ad-hoc addresses are opt-in — address is rejected unless allow-arbitrary: true, and such connections carry no credentials.

  • TLS file paths are confined — with tls-dir set, 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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables 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.
      9
      4
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      12
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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