Terminal MCP Server

HTTP MCP server that exposes authenticated shell tools so grok.com can run commands on this machine.

Quick start

cd /root/terminal-mcp
cp .env.example .env
# Set TERMINAL_MCP_TOKEN: openssl rand -hex 32
chmod +x scripts/*.sh
./scripts/start.sh
curl http://127.0.0.1:3001/health

grok.com setup

1. Set tunnel mode in .env:

   TERMINAL_MCP_TUNNEL_MODE=true
   

2. Restart: ./scripts/stop.sh && ./scripts/start.sh
3. Tunnel: ./scripts/tunnel.sh — copy the URL and set TERMINAL_MCP_TUNNEL_HOST
4. Restart again after setting tunnel host
5. Register at grok.com/connectors → Custom:
   • URL: https://<tunnel-host>/mcp
   • Auth: Bearer <TERMINAL_MCP_TOKEN>

Stable tunnel URLs

• ngrok paid: reserved domain — set TERMINAL_MCP_TUNNEL_HOST once
• Cloudflare named tunnel: Cloudflare Tunnel docs — persistent hostname

Tools

Tool	Description
run_command	Run shell command (shell_mode: auto/shell/exec)
get_command_output	Poll background job (supports tail_bytes)
list_tasks	List all jobs
kill_task	Terminate background job
get_cwd_info	Environment and policy summary

Resources

• terminal://tasks/{task_id}/log — task output log

Security

Configured in config.toml:

• mode: blocklist (default), allowlist, or permissive
• Command blocklist / allowlist
• Webhook approval for destructive commands ([security.webhook])
• Sanitized child environment (no inherited secrets)
• Audit log: logs/audit.jsonl

systemd

sudo cp deploy/terminal-mcp.service /etc/systemd/system/
sudo systemctl enable --now terminal-mcp

Tests

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -q

Local Grok CLI

grok mcp add terminal --transport http \
  --header "Authorization=Bearer ${TERMINAL_MCP_TOKEN}" \
  http://127.0.0.1:3001/mcp