✨ 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

Required CLI parameters

• host — hostname or IP address of the remote machine
• user — SSH username

Optional CLI parameters

• port — SSH port, default 22
• password — SSH password
• key — path to a private SSH key
• 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

🧩 MCP configuration 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"
      ]
    }
  }
}

SSH key example

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

🤖 Claude Code example

Register the server in Claude Code:

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

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

🎯 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.