Terminal Control MCP Server for Secure Command Execution

Overview

This MCP (Model Context Protocol) server exposes a standardized, minimal interface for controlled terminal access and file management. It is designed to let external agents—models, orchestration systems, CI runners—perform common shell-like operations (run commands, list and transfer files, change directories) without giving full raw shell access. The protocol surface is small and predictable, making it easier to audit and restrict.

The server focuses on secure, auditable execution: configurable command allowlists, execution timeouts, workspace isolation, and persistent file storage. It is useful when you need an automated component (for example, an LLM agent) to interact with a project workspace or remote runtime in a repeatable, policy-controlled way.

Features

• Secure, programmatic command execution (with allowlist and timeout)
• Directory navigation and workspace scoping (cd, pwd)
• File operations: upload, download, read, write, delete, list
• Persistent per-workspace file storage
• JSON-based MCP-compatible API for easy integration with agents
• Execution logging and exit-code reporting
• Resource limits and sandboxing recommendations
• Docker-ready deployment and simple configuration

Installation / Configuration

Below are example steps to get the server running. Adjust language and package manager steps to your environment.

Clone the repository:

git clone https://github.com/GongRzhe/terminal-controller-mcp.git
cd terminal-controller-mcp

Run with Docker (recommended to isolate runtime):

# Build (if Dockerfile provided)
docker build -t terminal-mcp:latest .

# Run with a volume for persistent storage
docker run -d \
  -p 8080:8080 \
  -v /var/lib/terminal-mcp:/data \
  -e MCP_AUTH_TOKEN="your-secret-token" \
  --name terminal-mcp \
  terminal-mcp:latest

Example minimal configuration (YAML):

server:
  listen_addr: 0.0.0.0
  port: 8080
auth:
  token: "your-secret-token"
workspace:
  base_path: "/data/workspaces"
execution:
  allowed_commands:
    - ls
    - cat
    - pwd
    - echo
  max_runtime_seconds: 10
  max_output_bytes: 65536
logging:
  path: "/data/logs/exec.log"

Start locally (if a binary or script is provided):

./terminal-controller-mcp --config ./config.yaml

Available Resources

The server exposes a small set of MCP-style endpoints. Each accepts and returns JSON. Below is a representative table of endpoints and responsibilities.

Example /execute payload:

{
  "workspace": "project-123",
  "cwd": "src",
  "command": ["ls", "-la"],
  "timeout_seconds": 5
}

Example /execute response:

{
  "stdout": "README.md\nmain.go\n",
  "stderr": "",
  "exit_code": 0,
  "duration_ms": 12
}

Use Cases

• CI job debugging: Allow an automation agent to run diagnostic commands or fetch test logs from an ephemeral workspace without exposing a full remote shell.
• LLM-driven agents: Let an AI agent inspect files and run specific build/test commands through a small, auditable API instead of raw terminal access.
• Remote maintenance: Execute health-check scripts and collect output from a constrained, token-authenticated endpoint.
• File management: Automate uploads/downloads of artifacts and maintain versioned workspaces for reproducible runs.

Concrete example — run tests and fetch report:

1. POST /execute with [“go”, “test”, “./…”] in workspace “integration-run-42”.
2. If tests produce reports under “reports/”, POST /files/download?workspace=integration-run-42&path=reports/report.xml to stream the artifact back.

Security & Operational Recommendations

• Run the server inside a container or dedicated VM with minimal privileges.
• Use strict allowlists for permitted commands and avoid enabling shell expansion unless necessary.
• Enforce per-request timeouts and output size caps to prevent resource exhaustion.
• Restrict workspace base_path and sanitize workspace names to avoid path traversal.
• Rotate authentication tokens and log all requests with timestamps, requester identity, and execution metadata.
• Consider combining with OS-level sandboxing (e.g., chroot, user namespaces, seccomp) for stronger isolation.

Troubleshooting & Tips

• If commands hang, increase logging verbosity and capture the process tree for diagnostics.
• Use small workspaces for reproducible runs; purge stale workspaces periodically.
• When integrating with agents, prefer idempotent sequences: upload -> execute -> download -> cleanup.

This server is intended to be a small, auditable building block for safe, automated terminal interactions. Its constrained API makes it easier to review and secure than exposing raw SSH or unrestricted shells.