Content
# Termius MCP
[English](README.md) · [简体中文](README.zh-CN.md)
stdio MCP server for [Termius](https://termius.com/) Cloud.
Repository: [MiaM1ku/termius-mcp](https://github.com/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`.
```bash
pip install termius-mcp
```
On Debian/Ubuntu (PEP 668) use a venv or `pipx`:
```bash
pipx install termius-mcp
```
From a git clone:
```bash
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`):
```json
{
"mcpServers": {
"termius": {
"command": "termius",
"args": []
}
}
}
```
Codex (`contrib/mcp/codex.toml`, merge into `~/.codex/config.toml`):
```toml
[mcp_servers.termius]
command = "termius"
args = []
startup_timeout_sec = 30.0
tool_timeout_sec = 60.0
```
Pi / OMP (`~/.omp/agent/mcp.json`):
```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
```bash
termius login
```
The command prompts for `google` or `email` when stdin is a TTY.
You can also pass the method:
```bash
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:
```bash
termius status
```
Sign out:
```bash
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](LICENSE).
Connection Info
You Might Also Like
No recommendations available