mcpnet

MCP server exposing network device interactions as tools for LLM agents.

Problem

LLM agents need structured, safe access to network devices. Raw SSH is dangerous — one write erase from a hallucinating model and you've lost a production config. MCP (Model Context Protocol) provides a standard interface, but nobody has built the network operations toolkit for it.

Solution

mcpnet is a lightweight MCP server that exposes network device operations as well-defined tools with built-in safety guardrails. It implements JSON-RPC 2.0 over stdio, compatible with any MCP client (Claude Desktop, custom agents, etc.).

Architecture

┌─────────────┐     JSON-RPC 2.0      ┌──────────────┐
│  LLM Agent  │ ◄──── stdio ────────► │  MCP Server  │
│  (Claude,   │                        │              │
│   GPT, etc) │                        │  ┌────────┐  │
└─────────────┘                        │  │  Tool  │  │
                                       │  │Registry│  │
                                       │  └───┬────┘  │
                                       │      │       │
                                       │  ┌───▼────┐  │
                                       │  │Guard-  │  │
                                       │  │rails   │  │
                                       │  └───┬────┘  │
                                       │      │       │
                                       │  ┌───▼────┐  │
                                       │  │Transport│ │
                                       │  │ Layer   │ │
                                       │  └───┬────┘  │
                                       └──────┼──────┘
                                              │ SSH
                                       ┌──────▼──────┐
                                       │   Network   │
                                       │   Devices   │
                                       └─────────────┘

Features

• 11 MCP tools across 4 categories: device info, config, routing, commands
• Built-in guardrails — blocks dangerous commands (write erase, reload, debug all), validates config changes
• YAML inventory — device groups, credential management, defaults inheritance
• Pluggable transport — MockTransport for testing, NetmikoTransport for real devices
• MCP standard — JSON-RPC 2.0 protocol, compatible with Claude Desktop and custom agents

Install

pip install mcpnet

# With Netmiko for real device access:
pip install mcpnet[netmiko]

Quick Start

List Available Tools

mcpnet list-tools

Start MCP Server

# With mock transport (testing)
mcpnet serve

# With real devices
mcpnet serve --inventory devices.yml --transport netmiko

Inventory File (devices.yml)

defaults:
  platform: cisco_ios
  username: admin

groups:
  core:
    port: 22
  access:
    port: 22

devices:
  core-rtr-01:
    host: 10.0.0.1
    groups: [core]
  access-sw-01:
    host: 10.0.1.1
    groups: [access]

Available Tools

Tool	Category	Description
get_device_info	device_info	Comprehensive device info (version + interfaces)
get_interfaces	device_info	Interface status, IPs, counters
get_version	device_info	Software version and uptime
get_running_config	config	Full running configuration
get_config_section	config	Specific config section
diff_configs	config	Running vs startup diff
get_routes	routing	Routing table (optional prefix/protocol filter)
get_bgp_neighbors	routing	BGP neighbor summary
get_ospf_neighbors	routing	OSPF adjacencies
execute_show_command	commands	Safe show command execution
execute_config_commands	commands	Guarded config command execution

Guardrails

Commands are validated before execution:

Risk Level	Examples	Default
Critical (blocked)	write erase, reload, debug all, format	Always blocked
High (review)	router bgp, access-list, crypto, snmp-server community	Blocked unless allow_config_mode=True
Low (safe)	show *, display *, ping, traceroute	Always allowed

API

from mcpnet.server import MCPServer
from mcpnet.inventory import load_inventory

inventory = load_inventory("devices.yml")
server = MCPServer(inventory=inventory, transport_backend="netmiko")
server.serve_stdio()

License

MIT