TermSSH MCP

Terminal-first SSH access for MCP clients, AI agents, and remote automation.

Turn remote machines into agent-friendly, interactive terminal workflows — not just one-shot command execution.

✨ 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

🧠 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:

Direct CLI flags — good for quick tests or a single server
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.

Name		Name	Last commit message	Last commit date
docs		docs
image		image
src		src
test		test
.gitattributes		.gitattributes
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
opencode.jsonc		opencode.jsonc
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

TermSSH MCP

✨ Why TermSSH MCP

Latest release: v1.6.0

🧠 What makes it different

Terminal-first

Agent-ready

Stateful workflows

Upload included

Cross-platform

Clean tool surface

🚀 Core capabilities

🧰 Tool set

upload-file

upload-content

download_file

list_remote_directory

get_remote_file_info

Directory and metadata tools

terminal-start

terminal-write

terminal-read

terminal-resize

terminal-close

🔄 Typical workflow

🛠 Installation

Clone the repository

Install globally

⚙ Configuration

Direct CLI parameters

Required

Optional

Vault mode

Vault CLI parameter

Account selection behavior

Example vault file

Important key behavior

🧩 MCP configuration examples

Recommended: vault-based MCP config

MCP tool call example with account

MCP behavior when account is omitted

Direct CLI example

Direct CLI with SSH key

Real local-project vault pattern

🤖 Claude Code example

✅ Verified vault workflow

🎯 Great fit for

Developers

DevOps / infra teams

Agent builders

🏗 Development

📁 Project structure

🗺 Roadmap ideas

🔐 Security note

📜 License

🤝 Contributing

About

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`upload-file`

`upload-content`

`download_file`

`list_remote_directory`

`get_remote_file_info`

`terminal-start`

`terminal-write`

`terminal-read`

`terminal-resize`

`terminal-close`