TermSSH MCP

✨ Why TermSSH MCP

Latest release: v1.6.0

This release completes the SFTP file-operation workflow:

• Download remote files with overwrite disabled by default.

• List remote directory entries and inspect file metadata.

• Create/remove remote directories, delete files, and rename paths.

• Set remote POSIX permissions and modification times.

• Recursively upload and download directories, skipping symbolic links and enforcing a configurable maxFiles limit (default 10000).

• Use temporary files for transfers and opt in explicitly to overwriting existing destinations.

It also adds MCP tools for these operations, improves tool descriptions, and requires an explicit account selection in vault mode while binding the selected account to interactive terminal sessions.

Verification: npm run build succeeds and npm test passes all 36 tests. SFTP operations were covered by unit tests with mocks; a live SFTP server transfer was not part of release verification.

Most SSH tooling for AI workflows is built around run command → get output → done.

That falls apart when the real task is interactive:

• installers ask questions

• shells keep state

• debugging needs multiple steps

• deployments need uploads plus terminal control

• agents need to observe, react, and continue

TermSSH MCP is built for that gap.

Instead of pretending everything is a single command, it gives MCP clients a real operator-style workflow:

open a shell → write input → read output → keep context → upload files → continue working

Related MCP server: ssh-mcp

🧠 What makes it different

Terminal-first

Interactive terminal sessions are the core model, not an afterthought.

Agent-ready

Designed for MCP clients, coding agents, and automation loops.

Stateful workflows

Reuse active sessions so multi-step tasks feel natural and reliable.

Upload included

Move scripts, configs, payloads, and generated artifacts over SFTP.

Cross-platform

Works against Linux and Windows SSH targets.

Clean tool surface

Focused MCP tools for terminal control and remote file delivery.

🚀 Core capabilities

• Interactive SSH terminal sessions

• Incremental terminal read / write flow

• Managed terminal session reuse by default

• Optional forced multi-session creation

• Local file upload through SFTP

• Remote file download to the MCP host through SFTP

• Remote directory listing and file metadata inspection

• Remote directory create/remove and file delete/rename operations

• Recursive directory upload and download (regular files; symbolic links skipped)

• Remote permission and modification-time updates

• Atomic temporary-file transfers, explicit overwrite behavior, and transfer file-count limits

• Direct text and base64 content upload

• Terminal resize support

• Linux and Windows SSH target support

• MCP-native interface for AI tooling

🧰 Tool set

upload-file

Upload a local file from the MCP host machine to the remote SSH server using SFTP.

Parameters

• localPath — local source file path

• remotePath — destination path on the remote host

• createDirectories — create missing parent directories if needed

• overwrite — replace an existing remote file if present

• mode — optional POSIX mode such as 0644

upload-content

Upload direct text or base64 content to the remote server.

Parameters

• content — raw text or base64 payload

• encoding — utf8 or base64

• remotePath — destination path on the remote host

• createDirectories — create missing parent directories if needed

• overwrite — replace an existing remote file if present

• mode — optional POSIX mode such as 0644

download_file

Download a remote file to local disk on the MCP host. Parent directories are created automatically.

Parameters

• remotePath — absolute source path on the remote host

• localPath — destination path on the MCP host

• overwrite — replace an existing local file if true (default false)

list_remote_directory

List a remote directory's entries, types, sizes, and modification times.

Parameters

• remotePath — absolute directory path on the remote host

get_remote_file_info

Inspect a remote file or directory's type, size, permissions mode, and modification time.

Parameters

• remotePath — absolute path on the remote host

Directory and metadata tools

• create_remote_directory — create one directory, or parents when recursive=true.

• remove_remote_directory — remove an empty directory.

• delete_remote_file — permanently delete a remote file.

• rename_remote_path — move or rename a remote path; destination overwrite is opt-in.

• set_remote_file_metadata — optionally set POSIX mode and/or modifiedAt (date string).

• upload_directory / download_directory — recursively transfer regular files, skipping symbolic links. maxFiles limits file count (default 10000); overwrite is false by default.

These tools accept account when connecting through vault mode; it is required in that mode.

terminal-start

Start an interactive remote terminal session.

Parameters

• cwd — optional working directory after shell startup

• shell — optional shell binary

• platformHint — auto, linux, or windows

• elevated — attempt su elevation when configured

• cols — terminal width

• rows — terminal height

• env — optional environment variables

• multiSession — set true to force a new managed session instead of reusing an existing one

terminal-write

Write input into an active terminal session.

Parameters

• sessionId — target session id

• input — text to send

• appendNewline — append a newline automatically if needed

terminal-read

Read buffered output from a terminal session.

Parameters

• sessionId — target session id

• sinceSequence — only return output newer than a given sequence number

• maxChars — limit the size of returned output

• waitForMs — optional short polling delay

terminal-resize

Resize an active terminal session.

Parameters

• sessionId — target session id

• cols — new width

• rows — new height

terminal-close

Close a terminal session locally.

Parameters

• sessionId — target session id

🔄 Typical workflow

flowchart LR
    A[terminal-start] --> B[terminal-write]
    B --> C[terminal-read]
    C --> D{Need file?}
    D -- Yes --> E[upload-file / upload-content]
    D -- No --> F{Continue session?}
    E --> F
    F -- Yes --> B
    F -- No --> G[terminal-close]

This works especially well for:

• interactive package installs

• remote setup and provisioning

• deployments with artifact upload

• debugging services across multiple steps

• stateful shell workflows where context matters

🛠 Installation

Clone the repository

git clone https://github.com/rayss868/termssh-mcp.git
cd termssh-mcp
npm install
npm run build

Install globally

npm install -g termssh-mcp

⚙ Configuration

TermSSH MCP supports two configuration modes:

1. Direct CLI flags — good for quick tests or a single server

2. Vault file — recommended for real usage, especially when you want multiple VPS accounts and one active target

Direct CLI parameters

Required

• host — hostname or IP address of the remote machine

• user — SSH username

Optional

• port — SSH port, default 22

• password — SSH password

• key — path to a private SSH key file

• sudoPassword — optional password for sudo-oriented workflows

• suPassword — optional password for su-based elevation

• timeout — SSH ready timeout in milliseconds, default 60000

• maxChars — command-length validation limit, default 1000; use none or 0 for unlimited mode

Vault mode

Vault mode lets you store multiple SSH accounts in one JSON file and choose the target account per MCP tool call.

Vault CLI parameter

• vault — path to a vault JSON file

If --vault is provided, startup resolves accounts from the vault. If no vault is provided, TermSSH MCP falls back to direct CLI config.

Account selection behavior

• MCP tools now expose an account parameter in the built tool schema

• when vault mode is enabled, account should be set to one of the keys under accounts

• if account is omitted, runtime now fails with a clear error instead of silently choosing an account

• this was verified against live SSH MCP runtime: no account → reject, valid account → connect successfully

Example vault file

File: termssh-mcp-vault.json

{
  "activeAccount": "production",
  "accounts": {
    "production": {
      "host": "1.2.3.4",
      "port": 22,
      "user": "root",
      "key": "C:\\keys\\id_ed25519"
    },
    "staging": {
      "host": "5.6.7.8",
      "port": 22,
      "user": "ubuntu",
      "password": "example-password"
    }
  }
}

Important key behavior

• In vault mode, key must point to a private key file path

• toSshConfigFromVault() reads that file and passes the key contents to ssh2

• This fixes the private-key parsing issue that happens if a file path is sent directly as privateKey

🧩 MCP configuration examples

Recommended: vault-based MCP config

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "node",
      "args": [
        "build/index.js",
        "--vault=./termssh-mcp-vault.json",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

MCP tool call example with account

{
  "account": "production",
  "cwd": "/var/www/app",
  "platformHint": "linux",
  "multiSession": true
}

MCP behavior when account is omitted

If you call a vault-backed tool without account, runtime rejects the call and tells you to choose one of the configured account names.

Direct CLI example

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=1.2.3.4",
        "--port=22",
        "--user=root",
        "--password=pass",
        "--timeout=30000",
        "--maxChars=none"
      ]
    }
  }
}

Direct CLI with SSH key

{
  "mcpServers": {
    "termssh-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "termssh-mcp",
        "--",
        "--host=example.com",
        "--user=root",
        "--key=/path/to/private/key",
        "--timeout=30000"
      ]
    }
  }
}

Real local-project vault pattern

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "node",
      "args": [
        "D:/All_project/own/AI_Coder/MCP_Tools/ssh-mcp/build/index.js",
        "--vault=D:/All_project/own/AI_Coder/MCP_Tools/ssh-mcp/termssh-mcp-vault.json",
        "--timeout=1200000",
        "--maxChars=50000"
      ]
    }
  }
}

🤖 Claude Code example

Register the server in Claude Code with direct credentials:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=YOUR_HOST --user=YOUR_USER --password=YOUR_PASSWORD

Register the server in Claude Code with a vault file:

claude mcp add --transport stdio termssh-mcp -- node build/index.js --vault=./termssh-mcp-vault.json --timeout=120000 --maxChars=none

With SSH key authentication:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=example.com --user=root --key=/path/to/private/key

With extended timeout:

claude mcp add --transport stdio termssh-mcp -- npx -y termssh-mcp -- --host=192.168.1.100 --user=admin --password=your_password --timeout=120000 --maxChars=none

✅ Verified vault workflow

The vault flow has been verified against a live SSH connection:

• termssh-mcp-vault.json loaded successfully

• resolveSshConfigFromSources() resolved the active account correctly

• interactive SSH session startup via terminal-start succeeded after fixing key-file loading

This means the recommended production path is now:

MCP config → --vault=... → active account selection → interactive terminal session

🎯 Great fit for

Developers

• remote shell access from AI coding tools

• stateful debugging sessions

• script and config delivery

DevOps / infra teams

• service inspection

• deployment support

• multi-step remote operations

Agent builders

• terminal-native MCP workflows

• reusable sessions

• controlled remote automation loops

🏗 Development

Build the project:

npm run build

Run tests:

npm test

Use the MCP Inspector:

npm run inspect

📁 Project structure

• src/index.ts — MCP server entrypoint and tool registration

• src/ssh-connection-manager.ts — SSH connection and terminal lifecycle handling

• src/upload.ts — upload helpers and interactive session metadata helpers

• src/core.ts — shared validation and SSH utility primitives

• test/upload-and-terminal.test.ts — upload/session unit coverage

• test/maxChars.test.ts — command validation coverage

• test/smoke.ssh.test.ts — smoke tests for current exported behavior

🗺 Roadmap ideas

• richer session metadata inspection

• better remote session observability

• optional session persistence features

• more examples for Claude Code and MCP tools

• deployment-oriented workflow templates

🔐 Security note

TermSSH MCP gives remote access to systems over SSH. Use it only on infrastructure you own or are explicitly authorized to manage.

📜 License

Released under the MIT License.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for contribution guidance and CODE_OF_CONDUCT.md for expected behavior.