gNMIBuddy

Anover-engineeredandopinionatedtool that retrieves essential network information from devices using gNMI and OpenConfig models. Designed primarily for LLMs withModel Context Protocol (MCP)integration, it also provides a full CLI for direct use.

See theAPI definitionfor all available APIs and options.

- Python3.13+
- uv, see thedocsto install it.

Windows users: The repo require a Unix-like environment. UseWSL.

[!NOTE] Theget_logs()function only works on IOS-XR.

Devicesmustsupport gNMI and OpenConfig models listed below:

- openconfig-system >= 0.17.1
- openconfig-interfaces >= 3.0.0
- openconfig-network-instance >= 1.3.0

[!NOTE] If the required model for a function is not found, gNMIBuddy will return an error. If the model version is older than required, it will continue execution but warn the user about potential errors.

You can use the capabilities command to verify the supported models on a specific device. If you have many devices you can use the--deviceoption.

uvx --from git+https://github.com/jillesca/gNMIBuddy.git \ gnmibuddy device capabilities --all-devices

gNMIBuddy identifies devices by hostname and looks up their corresponding IP addresses and credentials from the inventory file.

[!CAUTION] Without a device inventory file, gNMIBuddy cannot operate.

Provide device inventory via--inventory PATHor setNETWORK_INVENTORYenv var.

[!TIP] Store environment variables in a.envfile.

The inventory must be aJSON listofDeviceobjects with these required fields:

- name: Device hostname
- ip_address: IP for gNMI connections
- nos: Network OS identifier

- iosxronly for now, use it even if you have other NOS. More will be added later.

- Username/Password: Requires bothusernameandpasswordfields
- Certificate-based: Requires bothpath_certandpath_keyfields

Schema:src/schemas/models.py|Example:xrd_sandbox.json

[ { "name": "xrd-1", "ip_address": "10.10.20.101", "nos": "iosxr", "username": "cisco", "password": "C1sco12345" }, { "name": "xrd-2", "ip_address": "10.10.20.102", "nos": "iosxr", "path_cert": "/opt/certs/device.pem", "path_key": "/opt/certs/device.key" } ]

[!TIP] Validate your inventory: Usegnmibuddy inventory validateto check your inventory file for proper format, valid IP addresses, required fields, and authentication configuration before running network commands.

# Replace xrd_sandbox.json with your actual inventory file echo '#!/usr/bin/env bash' > /tmp/gnmibuddy-mcp-wrapper \ && echo 'exec uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy-mcp "$@"' >> /tmp/gnmibuddy-mcp-wrapper \ && chmod +x /tmp/gnmibuddy-mcp-wrapper \ && NETWORK_INVENTORY=xrd_sandbox.json npx @modelcontextprotocol/inspector /tmp/gnmibuddy-mcp-wrapper

[!TIP] No repo cloning, no MCP client setup required! If you don't have XRd, seeTesting with DevNet Sandbox.

# Run directly without installation uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy --help # Example with commands uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy --inventory your_inventory.json device list

# Install the tool globally uv tool install git+https://github.com/jillesca/gNMIBuddy.git # Use it directly gnmibuddy --help gnmibuddy device info --device R1 # Uninstall when no longer needed uv tool uninstall gnmibuddy # To get updates uv tool upgrade gnmibuddy

# Build the image (no inventory needed) make build # Run it, mounting your inventory file read-only into the container # or set the NETWORK_INVENTORY in a .env file make run NETWORK_INVENTORY=/path/to/inventory.json # Tail logs / stop the container make logs make stop

[!TIP] Runmake helpfor the rest of the targets (restart,shell,clean,fresh).

You can test it locally with themodelcontextprotocol/inspector.

npx @modelcontextprotocol/inspector --transport http --server-url http://0.0.0.0:8000/mcp

The container expects a device inventory file at the path in theNETWORK_INVENTORYenvironment variable (/app/inventory.jsonby default). There's no bundled Kubernetes manifest — the exact mechanism depends on your cluster — but the requirement is generic:

- Build the image with any OCI-compatible builder (Docker, Buildah, Kaniko,docker buildx, your CI's own build step, etc.). TheContainerfileis standard and carries no device-specific data, so the resulting image is safe to push to your registry.
- Store the inventory as a KubernetesSecret.
- Mount thatSecretas a volume on the pod at/app/inventory.json(or mount it elsewhere and pointNETWORK_INVENTORYat that path via the pod's env).

# Clone and setup (one-time only) git clone https://github.com/jillesca/gNMIBuddy.git && cd gNMIBuddy # Install dependencies uv sync --frozen --no-dev

❯ uv run gnmibuddy.py --help ▗▄▄▖▗▖ ▗▖▗▖ ▗▖▗▄▄▄▖▗▄▄▖ ▗▖ ▗▖▗▄▄▄ ▗▄▄▄▗▖ ▗▖ ▐▌ ▐▛▚▖▐▌▐▛▚▞▜▌ █ ▐▌ ▐▌▐▌ ▐▌▐▌ █▐▌ █▝▚▞▘ ▐▌▝▜▌▐▌ ▝▜▌▐▌ ▐▌ █ ▐▛▀▚▖▐▌ ▐▌▐▌ █▐▌ █ ▐▌ ▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌▗▄█▄▖▐▙▄▞▘▝▚▄▞▘▐▙▄▄▀▐▙▄▄▀ ▐▌ An opinionated tool that retrieves essential network information from devices using gNMI and OpenConfig models. Designed primarily for LLMs with Model Context Protocol (MCP) integration, it also provides a full CLI. Help: https://github.com/jillesca/gNMIBuddy Python Version: 3.13.4 gNMIBuddy Version: 0.1.0 Usage: gnmibuddy.py [OPTIONS] COMMAND [ARGS]... 📋 Inventory Requirement: Provide device inventory via --inventory PATH, set NETWORK_INVENTORY env var, or use .env file (configurable with --env-file PATH) Options: -h, --help Show this message and exit -V, --version Show version information --log-level LEVEL Set logging level (debug, info, warning, error) --module-log-help Show detailed module logging help --all-devices Run on all devices concurrently --inventory PATH Path to inventory JSON file -e, --env-file PATH Path to .env file for configuration (default: .env in project root) --max-workers NUMBER Maximum number of concurrent workers for batch operations (--all-devices, --devices, --device-file) Commands: device (d) Device Information capabilities Get gNMI capabilities from a network device info Get system information from a network device list List all available devices in the inventory profile Get device profile and role information network (n) Network Protocols interface Get interface status and configuration mpls Get MPLS forwarding and label information routing Get routing protocol information (BGP, ISIS, OSPF) vpn Get VPN/VRF configuration and status topology (t) Network Topology neighbors Get direct neighbor information via LLDP/CDP adjacency Get network-wide IP adjacency analysis for complete topology network Get complete network topology information. Queries all devices in inventory. ops (o) Operations logs Retrieve and filter device logs validate Validate all collector functions (development tool) inventory (i) Inventory Management validate Validate inventory file format and schema Examples: gnmibuddy.py device info --device R1 gnmibuddy.py network routing --device R1 gnmibuddy.py --all-devices device list gnmibuddy.py inventory validate --inventory inventory.json gnmibuddy.py --env-file production.env device list gnmibuddy.py --env-file dev.env --log-level debug device info --device R1 Run 'gnmibuddy.py COMMAND --help' for more information on a command.

Recommended: Use uvx (no repository clone needed):

# Replace xrd_sandbox.json with your actual inventory file echo '#!/usr/bin/env bash' > /tmp/gnmibuddy-mcp-wrapper \ && echo 'exec uvx --from git+https://github.com/jillesca/gNMIBuddy.git gnmibuddy-mcp "$@"' >> /tmp/gnmibuddy-mcp-wrapper \ && chmod +x /tmp/gnmibuddy-mcp-wrapper \ && NETWORK_INVENTORY=xrd_sandbox.json npx @modelcontextprotocol/inspector /tmp/gnmibuddy-mcp-wrapper EOF

For local development (testing uncommitted changes):

# Run from your gNMIBuddy project directory (where pyproject.toml is located) cd /path/to/your/gNMIBuddy && \ NETWORK_INVENTORY=your_inventory.json \ npx @modelcontextprotocol/inspector \ uv run --frozen gnmibuddy-mcp

Choose the approach that fits your needs:

Standard MCP Clientsconfig works with Cursor, Claude Desktop, and any other client following the MCP specification. VSCode requires a specific format.

- uvx configs: Only updateNETWORK_INVENTORYpath to your inventory file
- dev configs: Update bothNETWORK_INVENTORYpath andcwdto your local project directory

Don't have network devices? Use theDevNet XRd Sandbox, follow the instructions to bring up a segment routing network with gNMI configured.

# If you cloned the repo # Enable gRPC on the DevNet XRd Sandbox ANSIBLE_HOST_KEY_CHECKING=False \ uvx --from "ansible-core==2.19.2" --with "paramiko,ansible" \ ansible-playbook ansible-helper/xrd_apply_config.yaml -i ansible-helper/hosts

Want to see how this MCP tool integrates with actual AI agents? Check outsp_oncall- a graph of agents that use gNMIBuddy to demonstrate real-world network operations scenarios.

@dataclass class NetworkOperationResult: device_name: str ip_address: IPAddress nos: NetworkOS operation_type: str status: OperationStatus data: Dict[str, Any] = field(default_factory=dict) metadata: Dict[str, Any] = field(default_factory=dict) error_response: Optional[ErrorResponse] = None feature_not_found_response: Optional[FeatureNotFoundResponse] = None

Batch operations (using--all-devices,--devices, or--device-file) return aBatchOperationResultobject containing:

- results: A list ofNetworkOperationResultobjects, one for each device
- summary: Aggregate statistics about the batch operation
- metadata: Additional batch operation metadata

@dataclass class BatchOperationResult: results: List[NetworkOperationResult] # One result per device summary: BatchOperationSummary metadata: Dict[str, Any] = field(default_factory=dict)

For more details, see theresponse schema definition.

Raw gNMI Data → Collector → Processor → Schema → Response

# Use default .env file gnmibuddy device list # Use custom environment file gnmibuddy --env-file production.env device list

# .env file # Network configuration NETWORK_INVENTORY=/path/to/inventory.json # Logging configuration GNMIBUDDY_LOG_LEVEL=debug GNMIBUDDY_MODULE_LEVELS=src.cmd=warning,src.inventory=debug GNMIBUDDY_STRUCTURED_LOGGING=true GNMIBUDDY_LOG_FILE=/custom/log/path.log GNMIBUDDY_EXTERNAL_SUPPRESSION_MODE=development # MCP debugging GNMIBUDDY_MCP_TOOL_DEBUG=true

[!NOTE] Environment variables serve as defaults and can be overridden by CLI arguments like--log-leveland--module-log-levels.

For detailed environment configuration options and advanced usage, seeEnvironment Configuration Guide

For complete logging environment variable documentation, seeLogging README