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

🔌 Have an MCP Client? (VSCode, Cursor, Claude Desktop)

Recommended: No installation required - runs directly from GitHub using uvx:

MCP Client	Configuration
VSCode	📋 Copy config
Standard MCP Clients	📋 Copy config

For Development - when you need to test local changes:

MCP Client	Configuration
VSCode	📋 Copy config
Standard MCP Clients	📋 Copy config

The "Standard MCP Clients" config works with any MCP client following the MCP specification (Cursor, Claude Desktop, etc.). VSCode uses a different format.

Setup:

uvx configs: Update the NETWORK_INVENTORY path to your inventory file
dev configs: Update the NETWORK_INVENTORY path and cwd to your local project directory

🛠️ CLI Usage (Direct Tool Usage)

For CLI users who want to use gNMIBuddy as a command-line tool:

One-time execution

# 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 as a persistent tool

# 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

The uvx method automatically builds and runs the tool in an isolated environment without affecting your system.

📖 CLI Reference

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

🤖 Development

Quick Testing with MCP Inspector

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

MCP Client Configuration

Choose the approach that fits your needs:

Use Case	VSCode	Standard MCP Clients
Production/Testing	📋 Copy config	📋 Copy config
Local Development	📋 Copy config	📋 Copy config

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

Configuration requirements:

uvx configs: Only update NETWORK_INVENTORY path to your inventory file
dev configs: Update both NETWORK_INVENTORY path and cwd to your local project directory

🧪 Testing with DevNet Sandbox

Don't have network devices? Use the DevNet XRd Sandbox, follow the instructions to bring up a MPLS network with docker, then configure gNMI with the included Ansible playbook:

# 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

If you didn't clone the repo use this command

# Self-contained command that downloads files automatically
ANSIBLE_HOST_KEY_CHECKING=False \
bash -c 'TMPDIR=$(mktemp -d) \
&& trap "rm -rf $TMPDIR" EXIT \
&& curl -s https://raw.githubusercontent.com/jillesca/gNMIBuddy/refs/heads/main/ansible-helper/xrd_apply_config.yaml > "$TMPDIR/playbook.yaml" \
&& curl -s https://raw.githubusercontent.com/jillesca/gNMIBuddy/refs/heads/main/ansible-helper/hosts > "$TMPDIR/hosts" \
&& uvx --from "ansible-core==2.19.2" --with "paramiko,ansible" ansible-playbook "$TMPDIR/playbook.yaml" -i "$TMPDIR/hosts"'

Test with the xrd_sandbox.json inventory file part of the repository.

If you have problems with Ansible

Enable manually gNMI. Apply this configuration to all XRd devices:

grpc
 port 57777
 no-tls

Don't forget to commit your changes to XRd.

Testing with AI Agents

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

📋 Response Format

gNMIBuddy provides structured, consistent responses for all network operations. The response format depends on whether you're targeting a single device or multiple devices.

Single Device Operations

Single device operations return a NetworkOperationResult object with detailed information about the operation, including status, data, metadata, and error handling.

@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

Batch operations (using --all-devices, --devices, or --device-file) return a BatchOperationResult object containing:

results: A list of NetworkOperationResult objects, 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 the response schema definition.

🏗️ Architecture

Schema Organization

gNMIBuddy uses a centralized schema approach for data contracts:

src/schemas/: Contains all shared data models and response contracts.
src/collectors/: Network telemetry data collectors following OpenTelemetry patterns.
src/processors/: Data transformation processors following OpenTelemetry patterns.

These schemas serve as contracts between different parts of the system, ensuring consistency across:

CLI and API interfaces.
Network operation responses.
Error handling and status reporting.
MCP tool integration.

Data Processing Pipeline

The application follows an OpenTelemetry-inspired architecture:

Raw gNMI Data → Collector → Processor → Schema → Response

Collectors gather data from network devices via gNMI.
Processors transform raw data into structured, LLM-friendly formats.
Schemas ensure consistent data contracts across the system.
Responses provide standardized output for CLI, API, and MCP interfaces.

⚙️ Environment Variables

gNMIBuddy supports environment variables for configuration, which work for both CLI and MCP server usage. Environment variables can be loaded from:

Command line arguments (highest priority)
Operating system environment variables
.env files (default: .env in project root)
Default values (lowest priority)

.env File Support

gNMIBuddy automatically loads environment variables from a .env file in the project root. You can specify a custom .env file using the --env-file option:

# Use default .env file
gnmibuddy device list

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

Example:

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

Global Configuration

Variable	Description	Values	Default
`NETWORK_INVENTORY`	Device inventory file path	File path	-
`GNMIBUDDY_LOG_LEVEL`	Global log level	`debug`, `info`, `warning`, `error`	`info`
`GNMIBUDDY_MODULE_LEVELS`	Module-specific log levels	`module1=debug,module2=warning`	-
`GNMIBUDDY_LOG_FILE`	Custom log file path (overrides sequential)	File path	`logs/gnmibuddy_XXX.log`
`GNMIBUDDY_STRUCTURED_LOGGING`	Enable JSON logging	`true`, `false`	`false`
`GNMIBUDDY_EXTERNAL_SUPPRESSION_MODE`	External library suppression	`cli`, `mcp`, `development`	`cli`
`GNMIBUDDY_MCP_TOOL_DEBUG`	Enable MCP tool debugging	`true`, `false`	`false`

Sequential Log Files: gNMIBuddy automatically creates numbered log files (gnmibuddy_001.log, gnmibuddy_002.log, etc.) for each execution in the logs/ directory. The highest number is always the most recent run.

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

For detailed environment configuration options and advanced usage, see Environment Configuration Guide

For complete logging environment variable documentation, see Logging README

⚙️ Batch Operations & Concurrency

gNMIBuddy supports running commands across multiple devices simultaneously with configurable concurrency controls to optimize performance while avoiding rate limiting.

Batch Operation Options

Device Selection:

--device DEVICE: Single device operation
--devices device1,device2,device3: Comma-separated device list
--device-file path/to/devices.txt: Device list from file (one per line)
--all-devices: Run on all devices in inventory

Concurrency Controls:

--max-workers N: Maximum concurrent devices to process (default: 5)
--per-device-workers N: Maximum concurrent operations per device (default: varies by command)

Understanding Concurrency Levels

gNMIBuddy operates with two levels of concurrency:

Device-level concurrency (--max-workers): How many devices to process simultaneously
Per-device concurrency (command-specific): How many operations to run simultaneously on each device

Total concurrent requests = max_workers × per_device_operations

Examples

# Process 3 devices, 2 operations per device = 6 total requests
uv run gnmibuddy.py --max-workers 3 ops validate --devices xrd-1,xrd-2,xrd-3 --per-device-workers 2