termius-mcp 3.0.0__tar.gz

termius_mcp-3.0.0/AUTHORS

@@ -0,0 +1,7 @@
+andrey.lisin@gmail.com
+evgene.oskin@gmail.com
+eoskin@crystalnix.com
+maximbeiner@gmail.com
+mbeiner@crystalnix.com
+rkudiyarov@crystalnix.com
+yan.kalchevskiy@crystalnix.com

termius_mcp-3.0.0/LICENSE

@@ -0,0 +1,30 @@
+Copyright (c) 2020, Termius Corporation.
+
+Redistribution and use in source and binary forms of the software as well
+as documentation, with or without modification, are permitted provided
+that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above
+  copyright notice, this list of conditions and the following
+  disclaimer in the documentation and/or other materials provided
+  with the distribution.
+
+* The names of the contributors may not be used to endorse or
+  promote products derived from this software without specific
+  prior written permission.
+
+THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
+NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE AND DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
+DAMAGE.

termius_mcp-3.0.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include AUTHORS
+include README.md
+include README.zh-CN.md
+include LICENSE
+include setup.py
+include contrib/mcp/termius.mcp.json
+include contrib/mcp/codex.toml

termius_mcp-3.0.0/PKG-INFO

@@ -0,0 +1,278 @@
+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).

termius_mcp-3.0.0/README.md

@@ -0,0 +1,229 @@
+# 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).