SurriyaGokul/NetMCP

🔴 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?

🚀 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

🎮 Optimization Profiles

Five research-backed profiles optimized for specific workloads:

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)

Planning & Validation

Execution & Safety

Privilege Management

📊 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

🔒 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:

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

📈 Performance Results

Real-world improvements measured across profiles:

🤝 Contributing

Contributions are welcome! Areas of interest:

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

📄 License

MIT License — see for details.