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

Related MCP server: Remote MCP Server

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

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