🌐 NetMCP

AI-Powered Linux Network Optimization via Model Context Protocol

![Python 3.10+](https://www.python.org/) ![MCP](https://modelcontextprotocol.io/) ![Linux](https://www.linux.org/) ![License: MIT](LICENSE) ![Live on FastMCP](https://netmcp.fastmcp.app/mcp)

Transform natural language into optimized network configurations

🔴 Live Server · Getting Started · Features · Profiles · Architecture · Tools

</div>

---

🔴 Live Server

NetMCP is live in production on FastMCP Cloud! Connect your MCP client to:

https://netmcp.fastmcp.app/mcp

No installation required—just point your AI assistant to the hosted server and start optimizing.

---

🎯 Overview

NetMCP is an MCP server that enables AI assistants like Claude to intelligently optimize Linux network performance. It bridges the gap between high-level optimization goals ("optimize my network for gaming") and low-level Linux commands (sysctl, tc, nft).

┌──────────────────┐      ┌──────────────────┐      ┌──────────────────┐
│   AI Assistant   │ MCP  │     NetMCP       │      │   Linux Kernel   │
│   (Claude, etc)  │◄────►│   Server         │─────►│   Network Stack  │
└──────────────────┘      └──────────────────┘      └──────────────────┘
         ▲                         │
         │                         ▼
    Natural Language        29 Config Cards
    "Reduce my latency"     5 Profiles
                            40+ Tools

✨ Why NetMCP?

| Traditional Approach | With NetMCP | |---------------------|-------------| | Manual sysctl tuning | Declarative optimization plans | | Copy-paste commands from forums | Research-backed profiles | | No rollback on failure | Automatic checkpoints & rollback | | Trial and error | Validated against safety policies | | Root access chaos | Controlled privileged execution |

---

🚀 Getting Started

Prerequisites

Linux (Ubuntu 20.04+, Debian 11+, or similar)
Python 3.10+
Network tools: ip, sysctl, tc, nft

Installation

git clone https://github.com/SurriyaGokul/mcp-net-optimizer.git
cd mcp-net-optimizer

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Enable privileged commands (one-time setup)
./setup_sudo.sh

Configure with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "netmcp": {
      "command": "python",
      "args": ["-m", "server.main"],
      "cwd": "/path/to/mcp-net-optimizer"
    }
  }
}

Run Standalone

python -m server.main

---

⚡ Features

🎴 29 Configuration Cards

Full coverage of the Linux networking stack:

16 Sysctl cards — TCP tuning, buffers, congestion control
8 Traffic Control cards — QoS, shaping, queuing
5 Firewall cards — Rate limiting, connection tracking, NAT

</td> <td width="50%">

🛡️ Enterprise Safety

Production-ready security features:

Command allowlisting — Only approved binaries execute
Automatic checkpoints — Snapshot before every change
Instant rollback — One command to restore state
Audit logging — Complete execution history

</td> </tr> <tr> <td>

🔧 40+ MCP Tools

Comprehensive network management:

Discovery — Interfaces, routes, DNS, latency tests
Planning — Type-safe optimization plans
Validation — Policy enforcement before execution
Execution — Atomic apply with rollback
Benchmarking — Before/after performance comparison

</td> <td>

🔐 Sudo Management

Flexible privilege escalation:

Passwordless setup — Run ./setup_sudo.sh once
Cached credentials — Authenticate once, cached 15 min
MCP tools — check_sudo_access, request_sudo_access
Secure by default — Only allowlisted commands

</td> </tr> </table>

---

🎮 Optimization Profiles

Five research-backed profiles optimized for specific workloads:

| Profile | Focus | Key Optimizations | Target Metrics | |---------|-------|-------------------|----------------| | 🎮 Gaming | Ultra-low latency | BBR, tcp_low_latency, fq qdisc | <20ms p95, <5ms jitter | | 📺 Streaming | Max throughput | Large buffers, BBR, HTB shaping | 90%+ link utilization | | 📞 Video Calls | Balanced | DSCP marking, moderate buffers | <150ms latency (ITU-T) | | 📦 Bulk Transfer | Maximum bandwidth | 128MB buffers, aggressive BBR | >1Gbps sustained | | 🖥️ Server | High concurrency | SYN cookies, conntrack, rate limits | 10K+ connections |

Example: Gaming Optimization

plan = {
    "iface": "eth0",
    "profile": "gaming",
    "changes": {
        "sysctl": {
            "net.ipv4.tcp_congestion_control": "bbr",
            "net.ipv4.tcp_low_latency": "1",
            "net.core.default_qdisc": "fq"
        },
        "qdisc": {"type": "fq"}
    }
}

---

🏗️ Architecture

Pipeline Flow

  DISCOVER          PLAN            VALIDATE         RENDER           APPLY
 ┌─────────┐    ┌─────────┐      ┌─────────┐     ┌─────────┐     ┌─────────┐
 │ Inspect │───►│ Declare │─────►│ Check   │────►│Generate │────►│ Execute │
 │ System  │    │ Intent  │      │ Policies│     │Commands │     │ Safely  │
 └─────────┘    └─────────┘      └─────────┘     └─────────┘     └─────────┘
      │              │                │               │               │
   30+ tools    Pydantic         Policy YAML      sysctl/tc/     Checkpoint
   No side      schemas          validation       nft scripts    + Rollback
   effects

Project Structure

mcp-net-optimizer/
├── server/
│   ├── main.py              # MCP server entry point
│   ├── registry.py          # Tool & resource registration
│   ├── schema/models.py     # Pydantic data models
│   └── tools/
│       ├── discovery.py     # 30+ system inspection tools
│       ├── planner.py       # Plan → Commands renderer
│       ├── validator.py     # Policy validation
│       ├── validation_engine.py  # Before/after comparison
│       ├── validation_metrics.py # Network benchmarks
│       ├── audit_log.py     # Execution logging
│       ├── apply/           # Command executors
│       │   ├── apply.py     # Orchestration + rollback
│       │   ├── checkpoints.py
│       │   ├── sysctl.py
│       │   ├── tc.py
│       │   └── nft.py
│       └── util/
│           ├── shell.py     # Safe command execution
│           └── policy_loader.py
├── policy/
│   ├── config_cards/        # 29 YAML card definitions
│   ├── profiles.yaml        # 5 optimization profiles
│   └── validation_limits.yaml
└── setup_sudo.sh            # Passwordless sudo setup

---

🔧 MCP Tools

Discovery (No Side Effects)

| Tool | Description | |------|-------------| | ip_info | Network interfaces and addresses | | ip_route | Routing table | | ping_host | ICMP latency test | | traceroute | Network path analysis | | tc_qdisc_show | Traffic control status | | nft_list_ruleset | Firewall rules | | ss_summary | Socket statistics |

Planning & Validation

| Tool | Description | |------|-------------| | validate_change_plan_tool | Validate plan against policies | | render_change_plan_tool | Convert plan to executable commands | | test_network_performance_tool | Run comprehensive benchmarks | | validate_configuration_changes_tool | Compare before/after results |

Execution & Safety

| Tool | Description | |------|-------------| | apply_rendered_plan_tool | Execute with checkpoint + rollback | | snapshot_checkpoint_tool | Manual checkpoint creation | | rollback_to_checkpoint_tool | Restore previous state | | list_checkpoints_tool | View available checkpoints |

Privilege Management

| Tool | Description | |------|-------------| | check_sudo_access_tool | Check if sudo is available | | request_sudo_access_tool | Authenticate for temporary access | | get_sudo_setup_instructions_tool | Setup help |

---

📊 Benchmarking & Validation

NetMCP includes a complete validation pipeline to measure optimization impact:

# 1. Run baseline benchmark
before = test_network_performance_tool(profile="gaming")

# 2. Apply optimizations
apply_rendered_plan_tool(rendered_plan)

# 3. Run post-optimization benchmark  
after = test_network_performance_tool(profile="gaming")

# 4. Compare and validate
result = validate_configuration_changes_tool(before, after, "gaming")
# → {"decision": "KEEP", "score": 75, "summary": "Latency improved 15%"}

Validation Decisions

| Score | Decision | Action | |-------|----------|--------| | ≥60 | KEEP | Changes improved performance | | 20-59 | UNCERTAIN | Mixed results, review recommended | | <20 | ROLLBACK | Performance degraded, auto-rollback available |

---

🔒 Security Model

Command Allowlisting

Only explicitly approved binaries can execute:

# server/config/allowlist.yaml
binaries:
  - /usr/sbin/sysctl
  - /usr/sbin/tc
  - /usr/sbin/nft
  - /usr/bin/ping
  - /usr/bin/iperf3
  # ... etc

Privilege Escalation

Three options for sudo access:

Permanent (Recommended): Run ./setup_sudo.sh — configures passwordless sudo for network commands only
Session-based: Use request_sudo_access_tool(password="...") — caches for 15 minutes
Manual: Run sudo -v in terminal before using MCP

---

📈 Performance Results

Real-world improvements measured across profiles:

| Profile | Metric | Improvement | |---------|--------|-------------| | Gaming | Latency | 10-30% reduction | | Gaming | Jitter | 20-40% reduction | | Streaming | Throughput | 2-4× on congested links | | Video Calls | Connection time | 15-25% faster | | Server | Connection capacity | 10× increase |

---

🤝 Contributing

Contributions are welcome! Areas of interest:

Additional configuration cards
New optimization profiles
Cross-platform support
Performance benchmarks
Documentation improvements

---

📄 License

MIT License — see LICENSE for details.

---

Built with ❤️ for the AI-native networking future

Report Bug · Request Feature