# 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