Termius MCP

English · 简体中文

stdio MCP server for Termius Cloud.

Repository: MiaM1ku/termius-mcp.

termius with no arguments is the MCP server. An MCP client starts that binary with no args. The process speaks newline-delimited JSON-RPC on stdin/stdout (MCP stdio). It negotiates protocolVersion 2025-11-25 or 2025-06-18 (echoes the client when supported). Login, vault sync, host lookup, SSH exec, and SFTP file transfer are tools.

termius login signs in from a terminal. Use it for Google SSO, email and password, and OTP.

This tree talks to Termius desktop 10.0.6 APIs (DeviceToken, SRP / gRPC login, RNCryptor v3 and Sodium v4/v5, v4/terminal/sync/).

Install

Python 3.9+ is required. The PyPI name is termius-mcp. The official Termius CLI already uses termius. After install, the command is still termius.

pip install termius-mcp

On Debian/Ubuntu (PEP 668) use a venv or pipx:

pipx install termius-mcp

From a git clone:

python3 -m venv ~/.local/share/termius-mcp
~/.local/share/termius-mcp/bin/pip install -U pip
~/.local/share/termius-mcp/bin/pip install -e .
ln -sf ~/.local/share/termius-mcp/bin/termius ~/.local/bin/termius

Point the MCP client at that binary. Do not pass mcp or other args. Do not pass login in the MCP client args list.

Claude / generic (contrib/mcp/termius.mcp.json):

{
  "mcpServers": {
    "termius": {
      "command": "termius",
      "args": []
    }
  }
}

Codex (contrib/mcp/codex.toml, merge into ~/.codex/config.toml):

[mcp_servers.termius]
command = "termius"
args = []
startup_timeout_sec = 30.0
tool_timeout_sec = 60.0

Pi / OMP (~/.omp/agent/mcp.json):

{
  "mcpServers": {
    "termius": {
      "type": "stdio",
      "command": "termius",
      "args": []
    }
  }
}

Restart the MCP client after you edit the config. connecting [stdio] is the handshake. It becomes connected when initialize succeeds. Sign in with termius login before that, or use the login tools after connect.

Optional environment variables:

Variable	Purpose
TERMIUS_VAULT_PASSWORD	Vault encryption password (preferred over the remember file)
TERMIUS_SYNC_TTL	Seconds before the next automatic pull. Default 60. 0 pulls on every read.

First-time setup

Sign in from a terminal, then start the MCP client.

Terminal login

termius login

The command prompts for google or email when stdin is a TTY. You can also pass the method:

termius login google
termius login email -u you@example.com

Google:

1. Open the printed https://account.termius.com/sso/desktop?... URL.
2. Sign in with Google.
3. When the page tries to open Termius, copy termius://app/continue-sso?....
4. Paste that URL.
5. Enter the vault encryption password from the Termius app. This is not the Google password.
6. If 2FA is on, enter the OTP.

Email:

1. Enter the Termius email if you did not pass -u.
2. Enter the vault / account password.
3. If 2FA is on, enter the OTP.

TERMIUS_VAULT_PASSWORD supplies the vault password and skips the prompt. Default remember writes ~/.termius/vault mode 0600. Pass --no-remember to skip that file.

Check the session:

termius status

Sign out:

termius logout

MCP tools

After the server is connected, you can also use the tools.

If ~/.termius/config already has a DeviceToken (a previous login):

1. Call status. Expect logged_in: true and often vault_remembered: false.
2. Call sync with the vault encryption password from the Termius app (not the Google password). Default remember=true writes ~/.termius/vault mode 0600.
3. Call hosts. Later reads auto-pull when the cache is older than TERMIUS_SYNC_TTL.

If this machine has never signed in and you are not using termius login:

1. Call status. Expect logged_in: false.
2. Google: call login with method=google. Open the returned URL. Sign in. When the page tries to open Termius, copy termius://app/continue-sso?.... Call login_complete with that URL and the vault encryption password.
3. Email: call login with method=email, username, and the vault password. Add otp if 2FA is on.
4. Call hosts.

The process never returns the vault password in a tool result.

Tools

Call status first.

Tool	Purpose
status	Login state, last sync, stale flag, vault remembered, counts. Does not pull.
login	method=email with username + password, or method=google to get an SSO URL
login_complete	Finish Google SSO with callback_url + vault password
logout	Clear the session, remembered password, and local inventory
sync	Force a cloud pull now
hosts	List hosts (optional query)
host	One host + merged SSH settings + ssh_command
exec	Run a remote command over SSH
files	SFTP list / stat / read / write / get / put / mkdir / rm / rename
inventory	kind=groups|identities|keys|snippets

hosts, host, exec, files, and inventory pull automatically when the local cache is older than TERMIUS_SYNC_TTL and a vault password is available.

files uses SFTP on the same SSH credentials as exec. get and put copy between the MCP host filesystem and the remote host. read and write move file content through the tool result (max 200000 bytes). get and put allow up to 50 MiB. list defaults path to the SSH login directory.

Local data

After a successful pull, decrypted inventory lives in:

• ~/.termius/config — DeviceToken, salts, last_synced
• ~/.termius/storage — hosts, groups, identities, keys, snippets (plaintext JSON)
• ~/.termius/ssh_keys/ — private key files
• ~/.termius/vault — remembered vault password, if you chose remember

Treat that directory as secret.

Encryption notes

Termius Cloud currently has two personal encryption schemas:

• v3 — per-field RNCryptor (AES-CBC + HMAC). REST login is enough.
• v5 — entity content blobs sealed with Argon2id + XChaCha20-Poly1305, plus SRP login.

The server auto-detects ciphertext version (A… = v3, B… = v5). Login uses gRPC/SRP first (desktop login_v2); REST is only the fallback for accounts that are not migrated (NOT_MIGRATED). For v5 SRP the vault password is Argon2id-hashed (libsodium interactive, 16-byte salt) and base64-encoded, then proven with Botan SRP-6a modp/srp/8192 + Blake2b-512. public_data / proof are uppercase hex without a 0x prefix (Android libtermius strips Botan's prefix before the gRPC/Socket.IO payload).

Team vaults: sync / auto-pull loads /api/v4/team/vault/keys/, unwraps each encrypted_with key with the personal X25519 keypair (ECDH + HChaCha20 + XChaCha20-Poly1305), and decrypts shared hosts/keys/identities. Entities whose vault key is missing are skipped, not deleted.

License

See LICENSE.