Skip to main content
Glama
idealinvestse

Terminal MCP Server

by idealinvestse
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • SSH MCP Server

    format37
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to securely execute shell commands on local machines through an SSH interface with session management, command execution, and sudo support.
    1
    -

  • Remote MCP Server

    OddbeakerLLC
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI tools like Claude to interact with a remote machine's file system and shell via a secure HTTPS endpoint. It provides standardized tools for executing shell commands, reading and writing files, and navigating directories.
    -

  • Terminal MCP Server

    AcosX
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables executing shell commands on the host system via an MCP tool, with JWT/OAuth authentication and audit logging for secure remote access.
    1
    MIT

  • exec-vps-mcp

    yding-git
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides AI agents with an unrestricted VPS root shell by executing arbitrary shell commands and returning structured results such as exit code, stdout, stderr, timeout, and truncation status.
    15
    MIT