mirror of
https://github.com/dtzp555-max/network-mcp-server.git
synced 2026-07-21 21:15:08 +00:00
feat: Network MCP Server v0.1.0 — SNMP backend with 5 tools
MVP with zero-dependency SNMP backend for AI-powered network management: - get_snmp_value: query single OID - walk_snmp_tree: walk OID subtree - get_device_info: vendor auto-detection, uptime, location - get_interfaces: interface status with human-readable output - discover_devices: subnet SNMP discovery Tech: FastMCP + pysnmp-lextudio, Python 3.10+ Works with: Cisco, Juniper, Arista, UniFi, Fortinet, and any SNMP device 23 tests passing Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -0,0 +1,160 @@
|
||||
# Network MCP Server
|
||||
|
||||
AI-powered network device management via SNMP. Query any vendor's devices — Cisco, Juniper, Arista, UniFi, Fortinet, and more — through the Model Context Protocol.
|
||||
|
||||
## Overview
|
||||
|
||||
Network MCP Server bridges the gap between AI assistants (Claude, Cursor, etc.) and network infrastructure. It provides 5 SNMP-based tools that let AI query device status, discover networks, and retrieve interface statistics — all through a standardized MCP interface.
|
||||
|
||||
**Zero vendor lock-in**: Works with any SNMP-enabled device from any manufacturer.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
AI Assistant (Claude Code / Cursor / etc.)
|
||||
↕ MCP Protocol (stdio or HTTP)
|
||||
Network MCP Server (FastMCP)
|
||||
↕ SNMP v1/v2c (pysnmp-lextudio)
|
||||
Network Devices (Cisco / Juniper / Arista / UniFi / ...)
|
||||
```
|
||||
|
||||
The server uses FastMCP for the MCP transport layer and pysnmp-lextudio for SNMP operations. All queries are read-only by design — no configuration changes are made to devices.
|
||||
|
||||
## Dependencies
|
||||
|
||||
| Package | Version | Purpose |
|
||||
|---------|---------|---------|
|
||||
| fastmcp | >=2.0.0 | MCP server framework |
|
||||
| pysnmp-lextudio | >=6.1.0 | SNMP protocol implementation (actively maintained pysnmp fork) |
|
||||
| pydantic | >=2.0 | Input validation |
|
||||
| pyyaml | >=6.0 | Configuration file parsing |
|
||||
|
||||
**Runtime**: Python 3.10+
|
||||
|
||||
## Usage
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
pip install network-mcp-server
|
||||
# or from source:
|
||||
git clone https://github.com/dtzp555-max/network-mcp-server.git
|
||||
cd network-mcp-server
|
||||
pip install -e .
|
||||
```
|
||||
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
# Run the server (stdio mode for Claude Code)
|
||||
network-mcp
|
||||
|
||||
# Or run directly
|
||||
python -m network_mcp.server
|
||||
```
|
||||
|
||||
### Claude Code Integration
|
||||
|
||||
Add to `~/.claude/settings.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"network": {
|
||||
"command": "network-mcp",
|
||||
"env": {
|
||||
"SNMP_COMMUNITY": "your_community_string"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then in Claude Code:
|
||||
- "Show me the device info for 192.168.1.1"
|
||||
- "What's the interface status on the core switch?"
|
||||
- "Discover all SNMP devices on 10.0.0.0/24"
|
||||
|
||||
### Available Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `get_snmp_value` | Query a single SNMP OID |
|
||||
| `walk_snmp_tree` | Walk an OID subtree |
|
||||
| `get_device_info` | Get device name, vendor, uptime, location |
|
||||
| `get_interfaces` | Get interface status table with traffic stats |
|
||||
| `discover_devices` | Scan a subnet for SNMP-enabled devices |
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `SNMP_COMMUNITY` | `public` | Default SNMP community string |
|
||||
| `SNMP_TIMEOUT` | `5.0` | Query timeout in seconds |
|
||||
| `SNMP_RETRIES` | `1` | Number of retries on timeout |
|
||||
| `NETWORK_MCP_CONFIG_DIR` | `~/.network-mcp` | Config directory path |
|
||||
|
||||
### Device Inventory (Optional)
|
||||
|
||||
Create `~/.network-mcp/devices.yaml`:
|
||||
|
||||
```yaml
|
||||
devices:
|
||||
core-switch:
|
||||
host: 192.168.1.1
|
||||
community: private_string
|
||||
|
||||
firewall:
|
||||
host: 10.0.0.1
|
||||
community: fw_community
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
All tools return structured error responses instead of raising exceptions:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "SNMP error: No SNMP response received before timeout",
|
||||
"host": "192.168.1.1"
|
||||
}
|
||||
```
|
||||
|
||||
Common error scenarios:
|
||||
- **Timeout**: Device is unreachable or SNMP is not enabled
|
||||
- **Authentication**: Wrong community string (no SNMP response)
|
||||
- **Large subnet**: Subnet scan limited to /22 (1024 hosts) max
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- **SNMP v1/v2c only** — SNMPv3 support planned for v0.2.0
|
||||
- **Read-only** — No SET operations by design (safety first)
|
||||
- **64-bit counters** — ifHCInOctets/ifHCOutOctets used when available, falls back to 32-bit
|
||||
- **Subnet discovery** — Max /22 (1024 hosts) to prevent accidental network floods
|
||||
- **No persistent state** — Each query is independent, no caching
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
# Setup
|
||||
git clone https://github.com/dtzp555-max/network-mcp-server.git
|
||||
cd network-mcp-server
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -e ".[dev]"
|
||||
|
||||
# Test
|
||||
pytest tests/ -v
|
||||
|
||||
# Lint
|
||||
ruff check src/ tests/
|
||||
```
|
||||
|
||||
## Roadmap
|
||||
|
||||
- **v0.2.0**: SNMPv3 support, SSH/Netmiko backend (Cisco IOS commands)
|
||||
- **v0.3.0**: UniFi REST API backend
|
||||
- **v0.4.0**: Configuration change tools (with safety guardrails)
|
||||
- **v1.0.0**: Multi-backend, production-ready
|
||||
Reference in New Issue
Block a user