mirror of
https://github.com/dtzp555-max/network-mcp-server.git
synced 2026-07-19 09:43:07 +00:00
taodengandClaude Opus 4.6
761bb8c16c
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>
161 lines
4.2 KiB
Markdown
161 lines
4.2 KiB
Markdown
# 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
|