MCP Server Command and Script Executor

Overview

MCP Server Command and Script Executor provides a terminal-like interface for running shell commands and scripts on an MCP (Model Context Protocol) server. It exposes a controlled API and optional WebSocket terminal so operators and automation systems can execute administrative commands, run scripts, or stream real-time output without direct shell access. The design focuses on fast interaction and safety controls such as command whitelisting, timeouts, and authentication.

This tool is useful when you need remote, programmatic control over a server for maintenance, debugging, or CI/CD tasks while avoiding full SSH access. It integrates well with orchestration tools or LLM-based agents that use MCP to request actions and expect command output or exit codes in return.

Features

• REST API for one-shot command and script execution
• WebSocket-based interactive terminal for streaming stdin/stdout/stderr
• Script repository support (run predefined scripts by name)
• Command whitelisting and execution timeouts
• Authentication via API tokens (bearer) and optional TLS
• Docker-friendly and configurable for systemd/service deployment
• Structured JSON responses with exit codes and output chunks
• Logging and optional audit trail for executed commands

Installation / Configuration

There are multiple ways to deploy the executor. Docker is the simplest for most environments. Alternatively, run from source.

Clone repository:

git clone https://github.com/g0t4/mcp-server-commands.git
cd mcp-server-commands

Docker (recommended):

# Build
docker build -t mcp-commands .

# Run (example)
docker run -d \
  -p 8080:8080 \
  -v /srv/mcp-scripts:/app/scripts:ro \
  -e MCP_API_TOKEN="replace-with-secure-token" \
  --name mcp-commands \
  mcp-commands

Run from source (Node.js example):

# install dependencies
npm install

# start with environment variables
MCP_PORT=8080 MCP_API_TOKEN="replace-with-secure-token" node server.js

Example configuration file (config.json):

{
  "port": 8080,
  "apiToken": "replace-with-secure-token",
  "tls": {
    "enabled": false,
    "certFile": "/path/to/cert.pem",
    "keyFile": "/path/to/key.pem"
  },
  "scriptsDir": "./scripts",
  "allowedCommands": ["ls", "cat", "df", "uptime", "systemctl"],
  "maxExecutionTimeSec": 30,
  "logCommands": true
}

Security notes:

• Always use TLS (enable in config) when exposing the API on public networks.
• Use strong, rotated API tokens and restrict network access with firewall rules.
• Limit allowedCommands and run the service with a non-privileged user.

Available Resources

The project typically exposes these endpoints and resources:

Client utilities:

• CLI wrapper script (examples/cli.sh) for quick curl-based usage
• Web UI module (optional) that connects to /ws/terminal for a browser shell
• Systemd unit example for running as a service

Use Cases

1. Remote maintenance without SSH keys:

   • Trigger package updates or restart services from an orchestration system.
   • Example: POST /api/exec with { “cmd”: “systemctl restart my-service” } authenticated with a bearer token.

2. CI/CD job step runner:

   • Execute deployment scripts stored in a controlled scripts directory.
   • Example: POST /api/scripts/run with { “script”: “deploy-prod.sh”, “args”: [“v1.2.3”] }.

3. Interactive debugging from a web console:

   • Open a WebSocket session to /ws/terminal to stream logs and interactively run diagnostic commands when an engineer needs a quick live session.

4. LLM-driven automation via MCP:

   • An agent using MCP can request the executor to run a pre-approved diagnostic script and ingest the structured output to inform next actions.

Example: non-interactive API call with curl

curl -sS -X POST https://mcp.example.com/api/exec \
  -H "Authorization: Bearer replace-with-secure-token" \
  -H "Content-Type: application/json" \
  -d '{"cmd":"uptime"}'

Example: start interactive terminal with wscat

wscat -c wss://mcp.example.com/ws/terminal -H "Authorization: Bearer replace-with-secure-token"
# then type commands; output streams back over WebSocket

Best practices

• Keep scripts in a read-only, version-controlled directory and expose only those names through the API.
• Enforce short execution timeouts and resource limits (CPU/memory) where possible.
• Audit and log all actions to a central logging system for traceability.
• Run the service under a dedicated user with minimal filesystem permissions.

For full implementation details, examples, and advanced configuration, see the repository: https://github.com/g0t4/mcp-server-commands.