Terminal MCP

Purpose

Terminal MCP lets an MCP client observe and, when explicitly enabled, send constrained input to whitelisted tmux sessions. It supports local STDIO and a loopback-only Streamable HTTP transport intended to sit behind an authenticated HTTPS tunnel.

Related MCP server: Ryan's Tmux MCP Server

Architecture

Claude / Codex / shell
        |
       tmux
        |
   Terminal MCP
        |
 MCP (STDIO or loopback HTTP)
        |
     ChatGPT

tmux is the source of truth. The server calls tmux with explicit argument arrays through Python subprocess; it never uses shell=True.

Quick start

cd /home/dell/workspace/terminal-mcp
python3 -m venv .venv
.venv/bin/pip install -e '.[test]'
.venv/bin/terminal-mcp

For the remote-capable, loopback-only Streamable HTTP mode:

.venv/bin/terminal-mcp-http
# MCP endpoint: http://127.0.0.1:8766/mcp

The HTTP bind address is deliberately fixed to 127.0.0.1. Do not expose it directly or change it to 0.0.0.0; use an authenticated HTTPS tunnel that maps only its MCP route.

The installed user service can be managed with:

systemctl --user status terminal-mcp-http.service
systemctl --user restart terminal-mcp-http.service

Its unit is ~/.config/systemd/user/terminal-mcp-http.service, runs as the current user, and uses Restart=on-failure. Authentication is intentionally not implemented as an ad-hoc MCP wrapper: it must be enforced by the HTTPS tunnel/identity provider before traffic reaches the loopback endpoint.

For private ChatGPT Developer Mode connectivity, use OpenAI Secure MCP Tunnel. The credential-free deployment runbook and inactive service template are in deploy/secure-tunnel. No Cloudflare/public ingress is required for this mode.

Equivalent module command:

.venv/bin/python -m terminal_mcp.server

Example MCP client command configuration:

{
  "command": "/home/dell/workspace/terminal-mcp/.venv/bin/terminal-mcp",
  "args": [],
  "env": {
    "TERMINAL_MCP_CONFIG": "/home/dell/workspace/terminal-mcp/config.yaml"
  }
}

Config

config.yaml controls read/input permissions, allowed session patterns, and capture limits. Input is disabled by default.

permissions:
  terminal_read: true
  terminal_input: false
allowed_session_patterns:
  - "claude-*"
  - "codex-*"
  - "agent-*"
  - "test-*"
max_capture_lines: 2000
default_tail_lines: 200

Security model

• Sessions are denied unless their name matches a whitelist pattern.

• Sensitive names containing root, ssh, password, secret, or database require an exact literal whitelist entry.

• Output is sanitized for common API keys, bearer/authorization values, passwords, and tokens.

• There is no shell execution, arbitrary filesystem access, environment disclosure, process killing, scheduler, or autonomous agent.

• HTTP mode listens only on loopback and cannot change permissions or whitelist through requests.

• terminal_send_text uses tmux literal mode. terminal_send_keys accepts only a fixed V1 key allowlist.

• Errors do not reveal details about denied sessions.

Create an agent tmux session

tmux new -s claude-mesflow
claude

tmux new -s codex-mesflow
codex

Detach with Ctrl-b d and reattach with tmux attach -t SESSION.

Enable terminal input

Edit only the permission in config.yaml:

permissions:
  terminal_read: true
  terminal_input: true

Restart the MCP child process after changing configuration. Enabling input lets the MCP client type into allowed sessions; review this change carefully.

Tools

• terminal_list_sessions

• terminal_tail

• terminal_capture

• terminal_status

• terminal_send_text

• terminal_send_keys

• terminal_bind

• terminal_get_binding

• terminal_list_bindings

• terminal_unbind

• terminal_tail_bound

• terminal_status_bound

• terminal_send_bound

Chat ↔ tmux logical binding

A logical binding gives a chat or work context a stable name without relying on an internal ChatGPT conversation ID. Bindings persist in SQLite at ~/.local/state/terminal-mcp/bindings.db (or the path in TERMINAL_MCP_BINDINGS_DB) and resolve to tmux, which remains the source of truth.

Create an agent session:

tmux new -s claude-mesflow
claude

From ChatGPT, bind mesflow-dev to claude-mesflow with terminal_bind, then requests such as “xem agent này đang làm gì”, “đọc 300 dòng cuối”, or “kiểm tra nó đang chờ input không” can use:

terminal_tail_bound(binding="mesflow-dev")
terminal_tail_bound(binding="mesflow-dev", lines=300)
terminal_status_bound(binding="mesflow-dev")

Binding names contain only lowercase letters, digits, -, _, or ., with a maximum of 64 characters. A target must exist and pass the session whitelist; sensitive session names are never bindable. Existing bindings require replace=true for an explicit remap. If a tmux session disappears, its binding is retained and status becomes MISSING.

New bindings use read_enabled=true and input_enabled=false. Bound input is allowed only when both the local global permission and the binding permission are true. Creating a binding never enables global terminal input.

Known limitations

• Status detection is heuristic and intentionally returns UNKNOWN when evidence is weak.

• Only the active pane of each tmux session is inspected.

• Capture is line-based and capped; it does not stream incremental events.

• Redaction covers common secret shapes, not full DLP.

• HTTP mode is local-only until a separately authenticated HTTPS tunnel is configured.

• tmux sessions must run under the same Unix user as Terminal MCP.

terminal-mcp