TermSSH MCP

✨ Why TermSSH MCP

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

• 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

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.