NetOps MCP - Network Operations Tools MCP Server

1# NetOps MCP - Network Operations Tools MCP Server
2 
3A comprehensive Model Context Protocol (MCP) server that provides access to essential network operations and infrastructure tools through a standardized interface.
4 
5## 🚀 Features
6 
7### Network Connectivity Tools
8- **Ping**: Test host connectivity with customizable packet count and timeout
9- **Traceroute**: Trace network path with configurable max hops
10- **MTR**: Monitor network path with real-time statistics
11- **Telnet**: Test port connectivity using telnet
12- **Netcat**: Test port connectivity using netcat
13 
14### HTTP/API Testing Tools
15- **cURL**: Execute HTTP requests with full control over headers, methods, and data
16- **HTTPie**: Alternative HTTP client with simplified syntax
17- **API Testing**: Validate API endpoints with expected status codes
18 
19### DNS Tools
20- **nslookup**: Query DNS records with various record types
21- **dig**: Advanced DNS querying tool
22- **host**: Simple DNS lookup utility
23 
24### Network Discovery Tools
25- **Nmap**: Network scanning and service enumeration
26- **Port Scanning**: Targeted port scanning capabilities
27- **Service Discovery**: Identify running services on targets
28 
29### System Monitoring Tools
30- **SS**: Socket statistics and connection monitoring
31- **Netstat**: Network statistics and connection information
32- **ARP**: Address Resolution Protocol table management
33- **ARPing**: Test ARP connectivity
34 
35### System Information Tools
36- **System Status**: CPU, memory, and disk usage monitoring
37- **Process List**: Running process enumeration
38- **Required Tools Check**: Verify system tool availability
39 
40## 📋 Prerequisites
41 
42### Required System Tools
43The following tools must be installed on the system:
44 
45```bash
46# Network tools
47curl, ping, traceroute, mtr, telnet, nc (netcat)
48 
49# DNS tools
50nslookup, dig, host
51 
52# Network discovery
53nmap
54 
55# System tools
56ss, netstat, arp, arping
57 
58# HTTP tools
59httpie (optional, for enhanced HTTP testing)
60```
61 
62### Python Requirements
63- Python 3.8+
64- uv package manager (recommended)
65 
66## 🛠️ Installation
67 
68### Using uv (Recommended)
69 
70```bash
71# Clone the repository
72git clone https://github.com/alpadalar/NetOpsMCP.git
73cd NetOpsMCP
74 
75# Install dependencies using uv
76uv venv
77source .venv/bin/activate  # On Windows: .venv\Scripts\activate
78uv pip install -e .
79```
80 
81### Using pip
82 
83```bash
84# Clone the repository
85git clone https://github.com/alpadalar/NetOpsMCP.git
86cd NetOpsMCP
87 
88# Create virtual environment
89python -m venv .venv
90source .venv/bin/activate  # On Windows: .venv\Scripts\activate
91 
92# Install dependencies
93pip install -e .
94```
95 
96### Using Docker
97 
98```bash
99# Build and run with Docker Compose
100docker compose up -d
101 
102# Or build manually
103docker build -t netopsmcp .
104docker run -p 8815:8815 netopsmcp
105```
106 
107## 🚀 Quick Start
108 
109### 1. Start the Server
110 
111```bash
112# Using Python directly
113python -m netops_mcp.server_http --host 0.0.0.0 --port 8815
114 
115# Using Docker
116docker compose up -d
117 
118# Using the provided script
119./start_http_server.sh
120```
121 
122### 2. Test the Server
123 
124```bash
125# Health check
126curl http://localhost:8815/health
127 
128# Test system requirements
129curl -X POST http://localhost:8815/netops-mcp \
130  -H "Content-Type: application/json" \
131  -d '{"method": "check_required_tools", "params": {}}'
132```
133 
134### 3. Example Usage
135 
136```python
137# Ping a host
138result = ping_host("google.com", count=4, timeout=10)
139 
140# Test HTTP endpoint
141result = curl_request("https://httpbin.org/get", method="GET")
142 
143# DNS lookup
144result = nslookup_query("google.com", record_type="A")
145 
146# Network scan
147result = nmap_scan("192.168.1.1", ports="1-1000", scan_type="basic")
148```
149 
150## 📖 API Reference
151 
152### Network Connectivity
153 
154#### `ping_host(host: str, count: int = 4, timeout: int = 10)`
155Test connectivity to a host using ping.
156 
157**Parameters:**
158- `host`: Target hostname or IP address
159- `count`: Number of ping packets (default: 4)
160- `timeout`: Timeout in seconds (default: 10)
161 
162**Returns:** Ping statistics and results
163 
164#### `traceroute_path(target: str, max_hops: int = 30, timeout: int = 30)`
165Trace network path to a target.
166 
167**Parameters:**
168- `target`: Target hostname or IP address
169- `max_hops`: Maximum number of hops (default: 30)
170- `timeout`: Timeout in seconds (default: 30)
171 
172**Returns:** Network path information
173 
174#### `mtr_monitor(target: str, count: int = 10, timeout: int = 30)`
175Monitor network path using MTR.
176 
177**Parameters:**
178- `target`: Target hostname or IP address
179- `count`: Number of probes (default: 10)
180- `timeout`: Timeout in seconds (default: 30)
181 
182**Returns:** MTR statistics and hop information
183 
184### HTTP Testing
185 
186#### `curl_request(url: str, method: str = "GET", headers: dict = None, data: dict = None, timeout: int = 30)`
187Execute HTTP request using curl.
188 
189**Parameters:**
190- `url`: Target URL
191- `method`: HTTP method (GET, POST, PUT, DELETE, PATCH)
192- `headers`: HTTP headers dictionary
193- `data`: Request data for POST/PUT requests
194- `timeout`: Request timeout in seconds
195 
196**Returns:** HTTP response and timing information
197 
198#### `httpie_request(url: str, method: str = "GET", headers: dict = None, data: dict = None, timeout: int = 30)`
199Execute HTTP request using HTTPie.
200 
201**Parameters:** Same as curl_request
202 
203**Returns:** HTTP response and timing information
204 
205### DNS Tools
206 
207#### `nslookup_query(domain: str, record_type: str = "A", server: str = None)`
208Query DNS records using nslookup.
209 
210**Parameters:**
211- `domain`: Target domain name
212- `record_type`: DNS record type (A, AAAA, MX, NS, TXT, CNAME)
213- `server`: Custom DNS server (optional)
214 
215**Returns:** DNS query results
216 
217#### `dig_query(domain: str, record_type: str = "A", server: str = None)`
218Query DNS records using dig.
219 
220**Parameters:** Same as nslookup_query
221 
222**Returns:** Detailed DNS query results
223 
224### Network Discovery
225 
226#### `nmap_scan(target: str, ports: str = None, scan_type: str = "basic", timeout: int = 300)`
227Scan network using nmap.
228 
229**Parameters:**
230- `target`: Target hostname, IP, or network range
231- `ports`: Port range (e.g., "1-1000", "80,443,8080")
232- `scan_type`: Scan type (basic, full, stealth)
233- `timeout`: Scan timeout in seconds
234 
235**Returns:** Network scan results
236 
237#### `port_scan(target: str, ports: str, timeout: int = 60)`
238Perform targeted port scanning.
239 
240**Parameters:**
241- `target`: Target hostname or IP address
242- `ports`: Port range to scan
243- `timeout`: Scan timeout in seconds
244 
245**Returns:** Port scan results
246 
247### System Monitoring
248 
249#### `system_status()`
250Get system status information.
251 
252**Returns:** CPU, memory, and disk usage statistics
253 
254#### `ss_connections(state: str = None, protocol: str = None)`
255Show network connections using ss.
256 
257**Parameters:**
258- `state`: Filter by connection state
259- `protocol`: Filter by protocol
260 
261**Returns:** Network connection information
262 
263#### `netstat_connections(state: str = None, protocol: str = None)`
264Show network connections using netstat.
265 
266**Parameters:** Same as ss_connections
267 
268**Returns:** Network connection information
269 
270## 🧪 Testing
271 
272### Run All Tests
273 
274```bash
275# Using pytest
276pytest tests/ -v
277 
278# Using uv
279uv run pytest tests/ -v
280 
281# With coverage
282pytest tests/ --cov=src --cov-report=html --cov-report=term-missing
283```
284 
285### Test Categories
286 
287- **Unit Tests**: Individual tool functionality
288- **Integration Tests**: End-to-end workflow testing
289- **Mock Tests**: Command execution simulation
290- **Validation Tests**: Input validation and error handling
291 
292### Test Coverage
293 
294The test suite covers:
295- ✅ All tool methods and functionality
296- ✅ Input validation and error handling
297- ✅ Command execution and output parsing
298- ✅ Edge cases and error scenarios
299- ✅ Mock testing for external dependencies
300 
301To generate coverage reports:
302```bash
303# Generate HTML coverage report
304pytest tests/ --cov=src --cov-report=html
305 
306# Generate terminal coverage report
307pytest tests/ --cov=src --cov-report=term-missing
308 
309# Generate both reports
310pytest tests/ --cov=src --cov-report=html --cov-report=term-missing
311```
312 
313## 🔧 Configuration
314 
315### Environment Variables
316 
317```bash
318# Server configuration
319NETOPS_MCP_HOST=0.0.0.0
320NETOPS_MCP_PORT=8815
321NETOPS_MCP_LOG_LEVEL=INFO
322 
323# Tool timeouts
324PING_TIMEOUT=10
325TRACEROUTE_TIMEOUT=30
326MTR_TIMEOUT=30
327CURL_TIMEOUT=30
328NMAP_TIMEOUT=300
329```
330 
331### Configuration File
332 
333The server will automatically create a default configuration file from `config/config.example.json` on first run, or you can create `config/config.json` manually:
334 
335```json
336{
337  "logging": {
338    "level": "INFO",
339    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
340    "file": "logs/netops-mcp.log"
341  },
342  "security": {
343    "allow_privileged_commands": false,
344    "allowed_hosts": [],
345    "rate_limit_requests": 100,
346    "rate_limit_window": 60
347  },
348  "network": {
349    "default_timeout": 30,
350    "max_scan_timeout": 300,
351    "allowed_ports": "1-65535"
352  },
353  "server": {
354    "host": "0.0.0.0",
355    "port": 8815,
356    "path": "/netops-mcp"
357  }
358}
359```
360 
361## 🐳 Docker Support
362 
363### Docker Compose
364 
365```yaml
366version: '3.8'
367services:
368  netopsmcp:
369    build: .
370    ports:
371      - "8815:8815"
372    environment:
373      - NETOPS_MCP_HOST=0.0.0.0
374      - NETOPS_MCP_PORT=8815
375    volumes:
376      - ./logs:/app/logs
377      - ./config:/app/config
378    healthcheck:
379      test: ["CMD", "curl", "-f", "http://localhost:8815/health"]
380      interval: 30s
381      timeout: 10s
382      retries: 3
383```
384 
385### Docker Build
386 
387```bash
388# Build image
389docker build -t netopsmcp .
390 
391# Run container
392docker run -d \
393  --name netopsmcp \
394  -p 8815:8815 \
395  -v $(pwd)/logs:/app/logs \
396  -v $(pwd)/config:/app/config \
397  netopsmcp
398```
399 
400## 📊 Monitoring and Logging
401 
402### Log Levels
403 
404- **DEBUG**: Detailed debugging information
405- **INFO**: General operational messages
406- **WARNING**: Warning messages for potential issues
407- **ERROR**: Error messages for failed operations
408 
409### Log Files
410 
411- `logs/netops-mcp.log`: Main application log
412- `logs/access.log`: HTTP access log
413- `logs/error.log`: Error log
414 
415### Health Checks
416 
417```bash
418# Check server health
419curl http://localhost:8815/health
420 
421# Check system requirements
422curl -X POST http://localhost:8815/netops-mcp \
423  -H "Content-Type: application/json" \
424  -d '{"method": "check_required_tools", "params": {}}'
425```
426 
427## 🔒 Security Considerations
428 
429### Network Security
430 
431- **Firewall Rules**: Configure appropriate firewall rules for the server port
432- **Access Control**: Implement authentication if needed
433- **Network Isolation**: Run in isolated network environments when possible
434 
435### Tool Security
436 
437- **Privileged Operations**: Some tools require elevated privileges
438- **Network Scanning**: Be aware of legal implications of network scanning
439- **Rate Limiting**: Implement rate limiting for resource-intensive operations
440 
441### Best Practices
442 
443- **Input Validation**: All inputs are validated before processing
444- **Error Handling**: Comprehensive error handling and logging
445- **Timeout Management**: Configurable timeouts for all operations
446- **Resource Limits**: Built-in resource usage limits
447 
448## 🚀 Production Deployment
449 
450### Quick Production Setup
451 
4521. **Generate API Keys**:
453   ```bash
454   python scripts/generate_api_key.py -n 2 --config config/config.json
455   ```
456 
4572. **Configure Security** (`config/config.json`):
458   ```json
459   {
460     "security": {
461       "require_auth": true,
462       "api_keys": ["your-generated-key-here"],
463       "rate_limit_requests": 100,
464       "rate_limit_window": 60
465     }
466   }
467   ```
468 
4693. **Deploy with Docker Compose**:
470   ```bash
471   docker compose up -d
472   ```
473 
4744. **Verify Deployment**:
475   ```bash
476   curl http://localhost:8815/health
477   ```
478 
479### Authentication
480 
481The server supports API key authentication for secure access:
482 
483```bash
484# Make authenticated request
485curl -X POST http://localhost:8815/netops-mcp \
486  -H "Authorization: Bearer YOUR_API_KEY" \
487  -H "Content-Type: application/json" \
488  -d '{"method": "ping_host", "params": {"host": "google.com"}}'
489```
490 
491### HTTPS Setup (Recommended)
492 
493Use a reverse proxy (nginx or Caddy) for HTTPS:
494 
495```nginx
496server {
497    listen 443 ssl http2;
498    server_name your-domain.com;
499    
500    ssl_certificate /path/to/cert.pem;
501    ssl_certificate_key /path/to/key.pem;
502    
503    location / {
504        proxy_pass http://localhost:8815;
505        proxy_set_header Host $host;
506        proxy_set_header X-Real-IP $remote_addr;
507    }
508}
509```
510 
511### Production Features
512 
513- ✅ **API Key Authentication**: Secure access control with Bearer tokens
514- ✅ **Rate Limiting**: Built-in rate limiting (100 req/min default)
515- ✅ **Input Validation**: Comprehensive input sanitization
516- ✅ **Structured Logging**: JSON logging for production environments
517- ✅ **Health Checks**: Built-in health check endpoints
518- ✅ **Docker Support**: Production-ready Docker image with multi-stage build
519- ✅ **Non-Root User**: Runs as unprivileged user in container
520- ✅ **Resource Limits**: Configurable CPU and memory limits
521- ✅ **CORS Support**: Configurable CORS for web applications
522- ✅ **Security Headers**: Automatic security headers
523 
524### CI/CD Pipeline
525 
526GitHub Actions workflows included:
527- **Tests**: Automated testing on Python 3.10, 3.11, 3.12
528- **Linting**: Code quality checks (Black, Ruff, mypy)
529- **Security**: Security scanning (Bandit, Safety, Trivy)
530- **Release**: Automated Docker image publishing to GitHub Container Registry
531 
532### Documentation
533 
534- 📖 [Production Deployment Guide](docs/PRODUCTION_DEPLOYMENT.md)
535- 🔐 [API Authentication Guide](docs/API_AUTHENTICATION.md)
536- 🛡️ [Security Policy](SECURITY.md)
537 
538## 🤝 Contributing
539 
540### Development Setup
541 
542```bash
543# Clone repository
544git clone https://github.com/alpadalar/NetOpsMCP.git
545cd NetOpsMCP
546 
547# Install development dependencies
548uv pip install -e .
549 
550# Run tests
551pytest tests/ -v
552```
553 
554### Code Style
555 
556- **Black**: Code formatting
557- **Ruff**: Linting and import sorting
558- **mypy**: Type checking
559 
560### Testing Guidelines
561 
562- Write tests for all new functionality
563- Maintain test coverage above 90%
564- Use meaningful test names and descriptions
565- Mock external dependencies
566 
567### Pull Request Process
568 
5691. Fork the repository
5702. Create a feature branch
5713. Make your changes
5724. Add tests for new functionality
5735. Update documentation
5746. Submit a pull request
575 
576## 📄 License
577 
578This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
579 
580## 🆘 Support
581 
582### Documentation
583 
584- API Reference: See the API Reference section above
585- Configuration Guide: See the Configuration section above  
586- Troubleshooting: See the Support section above
587 
588### Issues
589 
590- **Bug Reports**: Use GitHub Issues
591- **Feature Requests**: Submit via GitHub Issues
592- **Security Issues**: Contact maintainers directly
593 
594### Community
595 
596- **Issues**: GitHub Issues for discussions and questions
597- **Documentation**: See the sections above for comprehensive guides
598 
599## 🙏 Acknowledgments
600 
601- **MCP Protocol**: Model Context Protocol specification
602- **Network Tools**: Open source networking utilities
603- **Testing Framework**: pytest and related tools
604- **Community**: Contributors and users
605 
606---
607 
608**NetOps MCP** - Empowering network operations through standardized tool access.
609