jbmurphy/mcp-cli

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)

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

environment:
  - PORT=3017  # HTTP server port

Using with Claude Desktop

Add to your Claude Desktop MCP configuration (~/.claude/mcp.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:

# 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

# 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

# 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

# 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

# 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