# Terminal MCP Server

HTTP MCP server that exposes authenticated shell tools so [grok.com](https://grok.com) can run commands on this machine.

## Quick start

```bash
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](https://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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — 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

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

## Tests

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

## Local Grok CLI

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