README.md•9.85 kB
# MCP CLI Command Server
A Model Context Protocol (MCP) server that provides safe, controlled access to common network and system CLI commands. This server enables AI assistants to execute whitelisted commands like nmap, ping, dig, and curl programmatically.
## What is MCP?
The Model Context Protocol (MCP) is an open protocol that enables AI assistants like Claude to securely interact with local tools and services. This server implements MCP to provide CLI command execution capabilities.
## Features
### Network Diagnostic Tools (4 tools)
- **cli_ping** - Ping hosts to check connectivity and measure latency
- **cli_traceroute** - Trace network route to destination hosts
- **cli_mtr** - Combined ping and traceroute diagnostic (MTR)
- **cli_netcat_test** - Test port connectivity using netcat
### Network Scanning Tools (2 tools)
- **cli_nmap_ping_scan** - NMAP host discovery on network ranges
- **cli_nmap_port_scan** - NMAP port scanning with service detection
### DNS Tools (3 tools)
- **cli_dig** - DNS lookups with multiple record type support
- **cli_host** - DNS host command for quick lookups
- **cli_whois** - WHOIS lookups for domains and IP addresses
### HTTP Tools (1 tool)
- **cli_curl_get** - HTTP GET requests with curl
## Quick Start
### Using Docker (Recommended)
```bash
# Build and start
docker-compose up -d
# View logs
docker logs -f cli-mcp-server
# Stop
docker-compose down
```
### Configuration
Edit `docker-compose.yml` to configure:
```yaml
environment:
- PORT=3017 # HTTP server port
```
### Using with Claude Desktop
Add to your Claude Desktop MCP configuration (`~/.claude/mcp.json`):
```json
{
"mcpServers": {
"cli": {
"type": "http",
"url": "http://localhost:3017/mcp",
"description": "CLI command execution for network and system diagnostics"
}
}
}
```
### Using with MCP Aggregator
The MCP Aggregator automatically discovers this server when configured:
```yaml
# In mcp-aggregator docker-compose.yml
environment:
- MCP_SERVER_CLI=http://host.docker.internal:3017
```
Tools will be available as `cli_*` (e.g., `cli_ping`, `cli_nmap_port_scan`)
## Testing
```bash
# Health check
curl http://localhost:3017/health
# List available tools
curl http://localhost:3017/mcp/list_tools | jq
# Test ping command
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_ping",
"arguments": {"host": "8.8.8.8", "count": 4}
}'
# Test nmap ping scan
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_nmap_ping_scan",
"arguments": {"target": "192.168.1.0/24"}
}'
# Test nmap port scan
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_nmap_port_scan",
"arguments": {
"host": "scanme.nmap.org",
"ports": "22,80,443",
"service_version": true
}
}'
# Test DNS lookup with dig
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_dig",
"arguments": {
"domain": "example.com",
"record_type": "A",
"short": true
}
}'
# Test HTTP request with curl
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_curl_get",
"arguments": {
"url": "https://api.github.com",
"headers_only": true
}
}'
# Test traceroute
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_traceroute",
"arguments": {"host": "google.com", "max_hops": 15}
}'
# Test WHOIS lookup
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_whois",
"arguments": {"target": "github.com"}
}'
# Test host lookup
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_host",
"arguments": {
"hostname": "cloudflare.com",
"record_type": "MX"
}
}'
# Test netcat port connectivity
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_netcat_test",
"arguments": {"host": "github.com", "port": 443, "timeout": 5}
}'
# Test MTR network diagnostic
curl -X POST http://localhost:3017/mcp/call_tool \
-H "Content-Type: application/json" \
-d '{
"name": "cli_mtr",
"arguments": {"host": "8.8.8.8", "cycles": 10}
}'
```
## API Endpoints
- `GET /health` - Health check
- `POST /mcp` - MCP HTTP transport (JSON-RPC 2.0) - **recommended**
- `GET /mcp/list_tools` - List available tools (REST)
- `POST /mcp/call_tool` - Execute a tool (REST)
## Security
### Whitelist-Only Approach
- **No Arbitrary Commands**: Only predefined, whitelisted commands are allowed
- **Argument Validation**: All arguments validated with regex patterns
- **No Shell Metacharacters**: Blocks `;`, `&&`, `||`, `|`, `$`, backticks, etc.
- **Timeout Enforcement**: All commands have maximum timeout limits
### Input Validation
- **IP Addresses**: Validated with regex (0-255 per octet)
- **Hostnames**: RFC-compliant hostname validation
- **Ports**: Range check (1-65535)
- **URLs**: Protocol and format validation
- **CIDR Notation**: IP and prefix validation
### Resource Limits
- **CPU**: Limited to 0.5 CPU cores
- **Memory**: Limited to 512MB
- **Timeouts**: Command-specific (5-600 seconds)
- **Non-Root User**: Runs as unprivileged user (uid 1000)
### Docker Security
- **No New Privileges**: `security_opt: no-new-privileges`
- **Minimal Capabilities**: Only NET_RAW and NET_ADMIN for network tools
- **Network Isolation**: Runs on isolated Docker network
- **Health Checks**: Automated container health monitoring
### Audit Logging
- All commands logged with timestamps
- Includes tool name, arguments, and execution time
- Exit codes and errors logged for troubleshooting
## Requirements
- Docker & Docker Compose
- Network connectivity for external scans
- Sufficient permissions for network tools (NET_RAW, NET_ADMIN capabilities)
## Port
**3017** - HTTP server for MCP protocol
## Architecture
- **Language**: Python 3.11
- **Framework**: Flask + MCP Python SDK
- **Transport**: HTTP with JSON-RPC 2.0
- **CLI Tools**: nmap, ping, curl, dig, traceroute, whois, host, netcat, mtr
## Installed CLI Tools
The Docker container includes these CLI tools:
- **nmap** - Network mapping and port scanning
- **iputils-ping** - ICMP ping utility
- **curl** - HTTP client
- **dnsutils** (dig, nslookup, host) - DNS utilities
- **traceroute** - Network path tracing
- **whois** - Domain/IP WHOIS lookup
- **netcat-traditional** - TCP/UDP connectivity testing
- **mtr-tiny** - Combined ping and traceroute
## Troubleshooting
### Container won't start
```bash
# Check if port 3017 is in use
lsof -i :3017
# View container logs
docker logs cli-mcp-server
# Check Docker network
docker network inspect mcp-network
```
### Permission errors
```bash
# Ensure container has network capabilities
docker inspect cli-mcp-server | jq '.[0].HostConfig.CapAdd'
# Should show: ["NET_RAW", "NET_ADMIN"]
```
### Commands fail with validation errors
- Ensure hostnames are valid (RFC-compliant)
- IP addresses must be in dotted-quad format (192.168.1.1)
- Ports must be 1-65535
- No shell metacharacters allowed in arguments
### Timeout errors
- Increase timeout parameter in tool arguments
- Check network connectivity from container
- Some commands have maximum timeout limits (security)
## Common Use Cases
### Network Troubleshooting
- Check if hosts are reachable with ping
- Trace network routes to diagnose connectivity issues
- Test port connectivity with netcat
### Security Scanning
- Discover active hosts on network with nmap
- Scan ports for open services
- Identify service versions
### DNS Diagnostics
- Look up DNS records with dig
- Verify DNS configuration
- Check domain ownership with WHOIS
### API Testing
- Test HTTP endpoints with curl
- Check response headers
- Verify SSL/TLS connectivity
## Development
```bash
# Rebuild after code changes
docker-compose up -d --build
# View detailed logs
docker logs cli-mcp-server --tail=100 -f
# Test locally without Docker
PORT=3017 python src/http_server.py
```
## Integration with Mattermost Bot
When integrated with the Mattermost Azure OpenAI bot via the MCP aggregator:
1. Bot discovers tools automatically (5-minute refresh)
2. Tools appear as `cli_*` functions
3. Use natural language: "Can you ping 8.8.8.8?"
4. Bot executes command and returns results in chat
Example conversation:
```
User: Can you check if github.com is reachable?
Bot: *calls cli_ping with host=github.com*
Bot: Yes, github.com is reachable! Average latency is 15ms.
User: Scan ports 22, 80, and 443 on scanme.nmap.org
Bot: *calls cli_nmap_port_scan*
Bot: Port scan results:
- Port 22 (SSH): Open - OpenSSH 7.9
- Port 80 (HTTP): Open - Apache 2.4
- Port 443 (HTTPS): Closed
```
## License
MIT License - See LICENSE file for details
## Contributing
Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request
## Support
For issues and questions:
- GitHub Issues: https://github.com/jbmurphy/mcp-cli/issues
- MCP Documentation: https://modelcontextprotocol.io
## Security Notice
⚠️ **Important**: This server executes network and system commands. While security measures are in place (whitelisting, validation, timeouts), use caution when exposing to untrusted networks or users.
**Best Practices:**
- Run on isolated Docker network
- Monitor command execution logs
- Review firewall rules for outbound scanning
- Limit access to trusted users/systems
- Keep container updated with security patches