npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

sshctl-mcp

v0.0.2

Published

Cross-platform SSH remote execution, passwordless key management, Windows Session 0 desktop launcher, SFTP transfers & MCP server

Readme

sshctl-mcp

npm version License: MIT Node.js MCP

Cross-platform SSH remote execution engine, passwordless key manager, Windows Session 0 desktop launcher, SFTP client, and Model Context Protocol (MCP) server for AI coding agents.


Architecture

Terminal / Human (CLI)             AI Agent (Claude / Antigravity / Cursor)
       │                                         │
       ▼                                         ▼
   sshctl (CLI binary)                  MCP Protocol (stdio JSON-RPC)
       │                                         │
       └──────────────────┬──────────────────────┘
                          ▼
                   Core SSH Engine
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
   Connection Pool    PowerShell/UTF-16LE   SFTP Channel
   (60s idle reuse)   (Session 0 / 8K limit) (FastPut / FastGet)
          │               │               │
          └───────────────┼───────────────┘
                          ▼
                  Remote Target Host
            (Windows / Linux / macOS)

Key Capabilities

  • Zero Local Client Shell Dependencies: Pure TypeScript built on ssh2. Executes uniformly across Windows (cmd, PowerShell), macOS, and Linux without requiring OpenSSH client binaries, WSL, Git Bash, sshpass, or iconv.
  • Native Windows Host Engineering: Automatically encodes Windows PowerShell commands into Base64 UTF-16LE (powershell.exe -EncodedCommand) to eliminate quote escaping bugs. Automatically falls back to SFTP script upload when command payloads exceed cmd.exe's 8,191-character boundary limit.
  • Windows Session 0 Desktop Handoff (--desktop / desktop: true): Solves the classic limitation where SSH-spawned GUI processes run invisibly in Session 0. Automatically hands off GUI processes to the active user's interactive desktop (Session 1) via Task Scheduler.
  • AI Agent Native (MCP Protocol): Exposes 9 first-class tools with rich parameter metadata, annotations (readOnlyHint, idempotentHint), token-efficient smart output capping (head/tail/compact), and prompt templates.
  • Transport Connection Pooling: Reuses underlying SSH2 connections per user@host:port with a 60-second idle timeout, eliminating handshake latency across multi-step agent workflows.
  • Secure Profile Management: Store targets in ~/.sshctl/profiles.json with environment variable indirection (env:VAR_NAME) so secret passwords are never leaked into agent conversation transcripts.

Installation & Setup

As an MCP Server (Recommended)

No manual clone or build required. You can run sshctl-mcp directly via npx.

1. Claude Code CLI

claude mcp add sshctl -- npx -y sshctl-mcp

2. Claude Desktop (claude_desktop_config.json)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "sshctl": {
      "command": "npx",
      "args": ["-y", "sshctl-mcp"]
    }
  }
}

3. Cursor / Windsurf / Cline (mcp.json)

{
  "mcpServers": {
    "sshctl": {
      "command": "npx",
      "args": ["-y", "sshctl-mcp"]
    }
  }
}

4. Google Antigravity

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "sshctl": {
      "command": "npx",
      "args": ["-y", "sshctl-mcp"]
    }
  }
}

For Antigravity lazy-loading tool schemas, run npm run export:schemas from a local clone.


As a Global CLI Tool

Install globally via npm:

npm install -g sshctl-mcp

Once installed, both sshctl and sshctl-mcp commands are available globally.

Alternatively, execute one-off commands without installing:

npx sshctl-mcp --help

From Source (Development)

git clone https://github.com/nguyenvanhuy0612/sshctl.git
cd sshctl
npm install
npm test        # 50 unit and integration tests (100% pass)
npm run build

Connection Profiles (~/.sshctl/profiles.json)

To avoid specifying credentials on every command or leaking passwords into agent conversation transcripts, define named profiles in ~/.sshctl/profiles.json:

{
  "win-host": {
    "host": "192.168.1.100",
    "port": 22,
    "username": "Administrator",
    "privateKeyPath": "~/.ssh/id_ed25519",
    "targetOs": "windows",
    "description": "Windows QA workstation"
  },
  "linux-box": {
    "host": "10.0.0.15",
    "port": 22,
    "username": "deploy",
    "password": "env:DEPLOY_PASSWORD",
    "targetOs": "linux",
    "description": "Linux CI runner"
  }
}
  • Values prefixed with env: are resolved dynamically from process environment variables at runtime.
  • Ensure profile permissions are restricted: chmod 600 ~/.sshctl/profiles.json.

CLI Command Reference

# List configured profiles
sshctl profiles

# Probe connectivity, target OS, and authentication
sshctl test win-host

# Execute remote command
sshctl exec win-host "Get-Process | Select-Object -First 10"

# Launch GUI app interactively on active Windows desktop (Session 1 bypass)
sshctl exec win-host "notepad.exe" --desktop

# Transfer files via SFTP
sshctl push win-host ./local-package.zip C:/Deploy/package.zip
sshctl pull win-host C:/Deploy/output.log ./output.log

# Generate Windows OpenSSH Server 1-liner bootstrap for RDP
sshctl bootstrap-rdp --admin

# Clear stale or changed host key from known_hosts
sshctl clear-hosts 192.168.1.100

# Start stdio MCP JSON-RPC server manually
sshctl mcp

MCP Tools Reference

| Tool | Read-Only | Description | | :--- | :---: | :--- | | ssh_list_profiles | Yes | List saved connection profiles from ~/.sshctl/profiles.json without exposing secret credentials. | | ssh_test_connection | Yes | Probe connectivity, detect remote OS (windows, linux, mac), and check auth methods. | | ssh_clear_known_hosts | No | Remove stale host entries from ~/.ssh/known_hosts via ssh-keygen -R with hashed and port support. | | ssh_exec | No | Execute remote command with Base64 UTF-16LE encoding, 8K boundary fallback, and optional Session 1 GUI bypass. | | ssh_setup_passwordless | No | Generate local ed25519 key (if missing) and install to target with strict ACLs for Windows or Linux. | | ssh_remove_passwordless | No | Remove deployed public key from remote target with automatic backup file creation. | | ssh_upload_file | No | Upload local file to remote destination over SFTP with automatic ancestor directory creation. | | ssh_download_file | No | Download remote file to local destination over SFTP with parent directory creation. | | ssh_generate_rdp_bootstrap| Yes | Generate a self-contained PowerShell one-liner to install and configure OpenSSH on Windows over RDP. |


Technical Documentation

  • docs/TOOLS.md: Parameter matrices, tool annotations, hints, and AI agent workflow patterns.
  • docs/REFERENCE.md: Deep architectural dive into PowerShell Base64 encoding, the 8,191-character boundary fallback, Windows Session 0 bypass mechanism, and exit code tables.

License

MIT © 2026 Nguyen Van Huy