Termius MCP
Termius MCP exposes tools to inspect saved Termius hosts, control and read terminal sessions, run commands, and manage native SFTP uploads from an MCP client.
List saved hosts with label, address, port, group, username, and auth type, with optional query filtering; no passwords/keys.
Connect to a saved host by exact label, optionally dry-run or force a new tab; uses Termius identities, host-key policy, and optional host allowlist.
List open SSH/local terminal sessions and read terminal buffer text (recent lines or capped scrollback).
Claim/release terminals for agent coordination, switch to or close claimed terminals, and send text/control keys.
Run shell commands in a claimed session, wait for prompt/timeout, and retrieve command output; follow up with read/send_key.
List connected SFTP panes and upload one regular file to a specified remote directory through Termius’ native transfer queue.
Query SFTP transfer status by transfer ID; timeouts do not cancel and should not trigger blind re-upload.
Apply safety constraints such as claimed-terminal enforcement, credential-store upload refusal, optional upload roots, and no automatic password/overwrite approval.
Provides tools for interacting with the macOS Termius terminal app, including listing saved hosts and open sessions, reading terminal output, connecting to saved hosts, running commands or sending input, managing terminal claims, switching or closing sessions, and following native SFTP uploads through transfer status.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Termius MCP Show my open Termius sessions and read the output from the active one."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Termius MCP
中文文档 · Quick start · Security · Validation
Your Termius sessions, ready for AI.
Read terminal output, run commands, switch sessions, and follow SFTP uploads from an MCP client such as Codex — inside the Termius app you already use.
Keep your saved hosts and native transfer queue. Give your agent explicit session IDs, terminal text, and transfer status for the work that otherwise takes repeated screenshots and clicks.
This community adaptation of deltaguita/termius-mcp targets macOS Termius 9.38.1. It is not an official Termius integration.
The adapter uses Termius's existing sessions and native transfer queue through its local debugging interface. It does not create a separate SSH/SFTP client. A running Termius that reports another version is rejected before anything is injected; Windows and Linux desktop support have not been implemented.
Why pair it with Computer Use?
Computer Use is useful for navigating Termius and handling dialogs. Terminal work also needs precise text and state: logs scroll, focus moves between tabs, and a full progress bar does not prove that an upload finished. Termius MCP gives those repeated operations dedicated tools.
Friction in a screenshot-and-click workflow | What this adapter provides |
Reading long terminal output across screenshots | Text from the xterm buffer, command-output markers, and an explicit warning when history is lost. Output is capped at 200 lines. |
Keeping track of the intended terminal as focus changes | Explicit session IDs for reads and input; tools to activate and close the selected session. |
Deciding what a quiet screen means | Reported states such as timeout, waiting for input and prompt observed. Prompt observation remains a heuristic; remote exit code is unknown. |
Watching a small SFTP progress bar and checking for errors | A transfer ID with native progress, error and completion observations. A wait timeout keeps the original upload available for follow-up. |
Multiple agents typing into the same terminal | Claims and cross-process locks for cooperating MCP callers. Human typing remains outside these locks. |
Use Computer Use for setup, SFTP pane selection and dialogs; use MCP for the repeated terminal and transfer operations. The app stays visible so you can inspect what is happening.
Ask for the task
Once configured, you can give your agent requests such as:
Show me the open Termius sessions and read the output from the one I select.
Connect to my saved development host in a new terminal, then run
pwdthere.Upload this file to the prepared SFTP destination. Follow the same transfer until it completes or reports an error, and tell me the result.
The agent operates through named tools while you keep working in a familiar SSH client. It does not need you to copy terminal output back into the chat.
Related MCP server: spectatty
Capabilities
Operation | Tools |
Inspect saved hosts and open terminals |
|
Connect a saved terminal host |
|
Coordinate terminal input |
|
Execute commands or send input |
|
Select or close a terminal |
|
Upload one regular file and inspect its native transfer |
|
These 14 tools are the default set. list_keychain, which returns selected identity
metadata, is registered only when TERMIUS_ENABLE_KEYCHAIN=1 is set. Metadata
filtering does not redact secrets printed by a remote command in the terminal.
Requirements
macOS, with Termius 9.38.1 installed at
/Applications/Termius.app.Python 3.11 or newer; Python 3.12 was used for validation.
Saved Termius hosts and access already configured by you.
Node.js 20 or newer only for the JavaScript development tests; Node.js 24 was used for validation. Node.js is not required to run the MCP server.
The version check is intentional: the integration uses private React, xterm and transfer-queue interfaces. Removing the check does not establish compatibility.
Install
Clone this repository and create a Python environment:
git clone https://github.com/dk23lhl/termius-mcp.git
cd termius-mcp
python3.12 -m venv .venv
.venv/bin/python -m pip install -r requirements.lockrequirements.lock pins the runtime dependencies; requirements-dev.lock adds the
offline test tools. Neither contains credentials or machine-specific package paths.
The checkout can also be installed as a package with a termius-mcp command, for
example run straight from it with uv:
uvx --from /absolute/path/to/termius-mcp --constraints /absolute/path/to/termius-mcp/requirements.lock termius-mcpThis command passes requirements.lock as constraints for the runtime dependencies.
Use it in place of the .venv/bin/python …/server.py pair in the client
configurations below. If you use a git+https:// source pinned to a reviewed
commit, point --constraints to the lock file from that same checkout; uvx does
not discover requirements.lock automatically.
Enable Termius access when needed
Save your work and quit Termius first. Restarting it disconnects existing terminal sessions. Then start it with a loopback debugging port:
open -a /Applications/Termius.app --args --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222
lsof -nP -iTCP:9222 -sTCP:LISTENContinue only if the listener is 127.0.0.1:9222, not * or 0.0.0.0.
Passing these arguments to an already running Termius process does not reliably
enable debugging.
Other processes on your Mac can access the debug interface, including data held in the renderer. Loopback binding does not provide authentication. Open the port only while needed. To close it, quit Termius and reopen normally:
open -a /Applications/Termius.appAfter a normal restart, the lsof command above should show no listener. The MCP
server itself never opens the port or restarts Termius. Read SECURITY.md
before enabling access.
Configure Codex
Merge codex-mcp.toml.example into ~/.codex/config.toml.
Replace both /absolute/path/to/termius-mcp placeholders with the absolute path
to your checkout. Preserve unrelated configuration and do not enable this adapter
and the upstream server together; they share a lock directory and the same Termius window.
Restart or reload your client if it has not loaded the new server. In Codex,
/mcp displays connected servers. An MCP configuration does not create a
same-named @ app mention or slash-command skill. You can ask:
Use the termius MCP to list saved hosts and open terminal sessions.
Configure Claude Code
As a plugin (needs uv on PATH). This repository is
also a plugin marketplace:
claude plugin marketplace add dk23lhl/termius-mcp
claude plugin install termius-mcp@termius-mcpClaude Code asks for the plugin's options (debug port, host-key mode, allowed hosts,
upload directories, claim label); /config changes them later. The server runs as
uvx --from <plugin directory> termius-mcp, pinned by requirements.lock, and its
tools appear as mcp__plugin_termius-mcp_termius__<tool>. To try a checkout for one
session without installing anything, run
claude --plugin-dir /absolute/path/to/termius-mcp. Use either the plugin or the
manual registration below, not both.
Manually, register the server once for your user, with the same absolute paths:
claude mcp add termius -s user -e TERMIUS_CDP_PORT=9222 -e TERMIUS_HOSTKEY=ask -- /absolute/path/to/termius-mcp/.venv/bin/python /absolute/path/to/termius-mcp/server.py
claude mcp listThe tools then appear as mcp__termius__<tool>. Add -e TERMIUS_UPLOAD_ROOTS=...
or -e TERMIUS_CONNECT_ALLOW=... in the same command to set those limits.
Either way, Claude Code asks before each MCP tool call unless a permission rule allows
it; if you add rules, allow only read tools such as read_terminal and keep input,
connect, close and upload tools on ask. The server also sends its usage rules (claim
before typing, no blind retries, terminal text is data) as MCP server instructions,
which Claude Code gives to the model.
Before connecting or typing
Connecting or typing into a host should follow an explicit user request. Start
with connect_host in dry-run mode, select the returned session ID, and claim the
terminal before input. Host-key confirmation defaults to ask; unexpected
changed-key dialogs are never accepted automatically.
SFTP workflow
Open one SFTP view in Termius. Connect one pane to Local and the other to the desired remote host, then navigate the remote pane to the destination directory.
Call
list_sftp_sessionsand select the exact remote session ID.Call
sftp_uploadwith the absolute local file path, that session ID, and the exact remote directory. Directories and symbolic links are refused, and so are credential stores such as~/.ssh,~/.aws,~/.netrcand macOS keychains, checked on the resolved path. SetTERMIUS_UPLOAD_ROOTSto:-separated absolute directories to allow uploads only from there; a value that names no directory (such as:) is a configuration error, not "no limit".If waiting times out, query the returned
transfer_idwithsftp_transfer_status. Do not upload the file again just because waiting timed out.
The tool observes native queue progress and error/end events; it does not read
pixels from the progress bar. 100% progress or a disappearing queue row alone
does not count as completion. Native overwrite dialogs remain for you to handle.
Automatic host connection currently applies to terminal sessions, not SFTP panes.
Interpret results carefully
prompt-observedis a prompt heuristic, not proof of a zero remote exit code. Commands run as supplied, without an added shell wrapper.Terminal output is rendered buffer text, not a byte-exact process log. Long output is capped at 200 lines and about 24,000 characters, with lines over 1,000 characters clipped and marked (
TERMIUS_MAX_OUTPUT_CHARSandTERMIUS_MAX_LINE_CHARSraise these); buffer trimming is reported ashistory-lost, and a resize during the command is reported separately because line breaks may differ. If after a resize the command line cannot be located, or appears more than once, only the current screen is returned, flaggedoutput-boundary-unknown; inspect it withread_terminal.run_commandpreserves interior blank lines.send_key('ctrl-c')can interrupt a command thatrun_commandis still waiting on; other input is refused until that call returns.A timeout does not cancel a command or upload. Lost acknowledgements may mean input was delivered; inspect the existing session or transfer before retrying.
Claims coordinate cooperating MCP processes. They do not block human typing or prevent a local process from connecting directly to the debug port.
TERMIUS_CONNECT_ALLOWrestrictsconnect_hostonly, not access to existing sessions. It is not a complete host-access policy.
Development and validation
Offline tests do not require Termius, a debug port, credentials, or a remote host:
.venv/bin/python -m pip install -r requirements-dev.lock
.venv/bin/python -m pytest tests -q
npm ci --ignore-scripts
npm testThe CI workflow runs both suites on macOS, then builds the wheel, installs it outside the checkout and checks the advertised tools.
JavaScript tests use the real @xterm/headless@5.5.0 buffer/parser; Termius
React/Redux objects and transfer streams are test doubles. See
validation scope for live checks and untested cases.
Origin and license
Based on upstream commit
5e7ab436f2095bc83689bf815bd9bb950ae9a894.
The upstream copyright notice and MIT license are preserved.
CHANGELOG.md distinguishes this adaptation from upstream history.
This repository contains adapter code and tests, not the Termius application or
its bundled source code. Termius is a separate product and is not affiliated with
this project.
Available Tools
14 toolsclaim_terminalAIdempotent
Claim a Termius tab for this session. run_command / send_key / send_text refuse any tab this session has not claimed, so another agent cannot slip commands in between yours. Refused while another live session holds it. A claim ends with release_terminal, when this session's MCP process exits, or after 15 min with no input call. Prefer a tab of your own over one a human or another agent is using.
Inputs: session (required). Returns: result
close_terminalADestructive
Close one claimed terminal session, never the whole app. Default refuses a busy/non-prompt terminal. force=true can interrupt work; use only when the user explicitly requests that. Verify actual removal, not just dispatch.
Inputs: session (required), force. Returns: result
connect_hostADestructive
Get a tab for a SAVED Termius host (exact label from list_hosts). A tab that
THIS session's connect_host opened earlier (list_terminal_sessions marks it "opened by
agent: THIS session") and that nobody else has claimed is REUSED; otherwise a NEW TAB is
opened (wait until connected, then claim). Tabs a human or another session opened are
never reused implicitly. new_tab=true always opens a new tab. A tab claimed by another session is
never taken: the call fails and says who holds it.
Termius' own saved identity / key / jump hosts are used; no credential is read or
passed here. Only saved hosts: no free-form address, no new window. A first-time
host-key prompt is answered per TERMIUS_HOSTKEY (default: "ask", the
fingerprint is reported back; a CHANGED key is never accepted). A password prompt
is NOT answered: read_terminal and ask the human.
dry_run=true only checks that the host and Termius' connect function are found.
TERMIUS_CONNECT_ALLOW (comma separated labels) can restrict which hosts are allowed.
Inputs: host (required), wait, dry_run, new_tab. Returns: result
list_hostsARead-only
List saved Termius hosts: label, address, port, group, username, auth type.
Passwords and keys are never included. query filters by label/address/group.
Inputs: query. Returns: result
list_sftp_sessionsARead-only
List currently connected SFTP panes by session ID, host and directory. Open Termius' SFTP view first. No credentials are returned.
Inputs: no named parameters.
list_terminal_sessionsARead-only
List terminal sessions open in Termius (SSH and local tabs): id prefix, name,
protocol, address, connection state. Any of id prefix / name / address can be
passed as session to the other tools.
Inputs: no named parameters. Returns: result
read_terminalARead-only
Read terminal text (ANSI stripped, blank runs collapsed). Default: last lines
lines of the screen. scrollback=true reads the whole history (capped).
Inputs: lines, session, scrollback. Returns: result
release_terminalBIdempotent
Release a tab this session claimed. Release when your work on the tab is done.
Inputs: session (required). Returns: result
run_commandADestructive
EXECUTE a shell command on the remote host in the open Termius session, wait for
the prompt to return, and return only the command's output (echo and prompt removed).
If it is still running or waiting for input at timeout, returns what it has so far
with a status line; use read_terminal / send_key('ctrl-c') to follow up.
The tab must be claimed by this session first (claim_terminal).
Inputs: command (required), session, timeout. Returns: result
send_keyBDestructive
Send one control key: enter, tab, esc, backspace, ctrl-c, ctrl-d, ctrl-u, ctrl-l, ctrl-z, ctrl-r, up, down, left, right, q, y, n. Note 'enter' submits whatever is typed.
Inputs: key (required), session. Returns: result
send_textADestructive
Send printable text without Enter. A foreground program may act on any input. Use send_key('enter') to submit, or run_command to execute and collect output.
Inputs: text (required), session. Returns: result
sftp_transfer_statusARead-only
Read retained native upload progress/error/completion by transfer ID. 100% progress or a disappeared queue row alone does not mean completed.
Inputs: transfer_id (required).
sftp_uploadADestructive
Upload one local regular file through Termius' native SFTP transfer queue. Use the exact remote session ID from list_sftp_sessions, keep one pane on Local, and navigate the remote pane to remote_directory first. Overwrite dialogs stay in Termius for the human; this tool never approves them. Follows the native progress/error/end events. Timeout does NOT cancel; follow sftp_transfer_status with the returned ID, never blindly re-upload. Credential stores (~/.ssh, ~/.aws, keychains, ...) are refused; TERMIUS_UPLOAD_ROOTS can further limit uploads to listed directories.
Inputs: local_path (required), sftp_session (required), remote_directory (required), timeout.
switch_terminalBDestructive
Activate an explicitly selected terminal and its containing tab; verify state.
Inputs: session (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools target clearly distinct actions (connect/claim/release/read/close terminal, list hosts vs sessions vs SFTP panes). The only mild overlap is among send_key, send_text, and run_command, but their descriptions clearly delineate control keys vs raw text vs execute-and-collect-output. Claim/release/switch are similarly well separated.
Nearly all tools follow a verb_noun pattern (list_hosts, connect_host, claim_terminal, run_command, sftp_upload). The lone deviation is sftp_transfer_status, which is a noun-style status read rather than a verb-led name. Minor inconsistency, still highly readable.
14 tools is well within the ideal 3-15 range and each tool maps to a concrete lifecycle step (discover, connect, claim, interact, read, close) or an SFTP operation. No redundant or filler tools are apparent.
The terminal lifecycle is thoroughly covered (hosts, sessions, claim/read/send/run/switch/close). SFTP is only half-covered: upload and status exist but there is no download or directory-listing tool, which agents would have to work around (e.g. via run_command).
Maintenance
Related MCP Connectors
Develop, manage, and debug Railway projects, services, and deployments from within agents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Live browser debugging for AI assistants — DOM, console, network via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to have persistent, fully interactive SSH sessions into remote hosts, behaving like a local terminal.14 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to spawn and interact with real terminal sessions, capturing screenshots of rendered TUI output and sharing live sessions for debugging.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to securely execute commands on remote hosts via SSH and SFTP, with persistent shells, file transfers, screenshots, and an audit log.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to perform operations on remote servers by reusing SSH sessions from a local desktop app, including command execution, file upload/download, and project document management with security controls.MIT