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

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

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.

Device Inventory file

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

Provide device inventory via --inventory PATH or set NETWORK_INVENTORY env var.

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

🚀 Quick Start

🎯 Instant Testing with MCP Inspector

Fastest way to try gNMIBuddy:

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

For Development - when you need to test local changes:

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

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

One-time execution

Install as a persistent tool

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

📖 CLI Reference

🤖 Development

Quick Testing with MCP Inspector

Recommended: Use uvx (no repository clone needed):

For local development (testing uncommitted changes):

MCP Client Configuration

Choose the approach that fits your needs:

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:

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

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

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.

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

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:

1. Collectors gather data from network devices via gNMI.

2. Processors transform raw data into structured, LLM-friendly formats.

3. Schemas ensure consistent data contracts across the system.

4. 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:

1. Command line arguments (highest priority)

2. Operating system environment variables

3. .env (default: .env in project root)

4. 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:

Example:

Global Configuration

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.

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:

1. Device-level concurrency (--max-workers): How many devices to process simultaneously

2. Per-device concurrency (command-specific): How many operations to run simultaneously on each device

Total concurrent requests = max_workers × per_device_operations

Examples