gNMIBuddy MCP Server

🧪 gNMIBuddy

An over-engineered and 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 for direct use.

Opinionated by design, over-engineered by passion. gNMI and YANG expose overwhelming amounts of data with countless parameters. This tool provides what I consider the most relevant information for LLMs. And who doesn't enjoy building complicated solutions.

🎯 What It Does

Retrieve structured network data in JSON format:

• 🔄 Routing: BGP, ISIS protocols and neighbor states
• 🔌 Interfaces: Status, configuration, and statistics
• 🏷️ MPLS: Labels, forwarding tables, and segment routing
• 🔒 VPN/VRF: L3VPN configuration and route targets
• 📝 Logs: Filtered device logs with keyword search
• 🏠 Topology: Device neighbors and network-wide topology analysis

See the API definition for all available APIs and options.

⚡ Prerequisites

• Python 3.13+
• uv, see the docs to install it.
  • brew is recommended for macOS users
• Network devices with gNMI enabled.

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

Device Compatibility

Tested on:

• Cisco XRd Control Plane (24.4.1.26I, 25.3.1)

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

Devices must support gNMI and OpenConfig models listed below:

OpenConfig Models dependencies

• 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 --device option.

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

Device Inventory file

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 PATH or set NETWORK_INVENTORY env var.

[!TIP] Store environment variables in a .env file.

The inventory must be a JSON list of Device objects with these required fields:

• name: Device hostname
• ip_address: IP for gNMI connections
• nos: Network OS identifier
  • iosxr only for now, use it even if you have other NOS. More will be added later.

Authentication (choose one method):

• Username/Password: Requires both username and password fields
• Certificate-based: Requires both path_cert and path_key fields

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: Use gnmibuddy inventory validate to check your inventory file for proper format, valid IP addresses, required fields, and authentication configuration before running network commands.

🚀 Quick Start

🎯 Instant Testing with MCP Inspector

Fastest way to try gNMIBuddy:

# 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, see Testing with DevNet Sandbox.