Metadata-Version: 2.4
Name: termius-mcp
Version: 3.0.0
Summary: Termius Cloud MCP server.
Home-page: https://github.com/MiaM1ku/termius-mcp
Author: MiaM1ku
Author-email: 61079068+MiaM1ku@users.noreply.github.com
License: BSD
Project-URL: Source, https://github.com/MiaM1ku/termius-mcp
Project-URL: Issues, https://github.com/MiaM1ku/termius-mcp/issues
Keywords: termius,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: Unix
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: requests>=2.7.0
Requires-Dist: cryptography>=3.2
Requires-Dist: six>=1.10.0
Requires-Dist: cached-property>=1.3.0
Requires-Dist: paramiko>=1.16.0
Requires-Dist: pathlib2>=2.1.0
Requires-Dist: blinker>=1.4
Requires-Dist: pynacl>=1.5.0
Requires-Dist: python-socketio>=5.11.0
Requires-Dist: websocket-client>=1.6.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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).
