@xiaoyankonling/ssh-mcp 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tufan Tunç
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,256 @@
+# SSH MCP Server
+
+[![NPM Version](https://img.shields.io/npm/v/@xiaoyankonling/ssh-mcp)](https://www.npmjs.com/package/@xiaoyankonling/ssh-mcp)
+[![Downloads](https://img.shields.io/npm/dm/@xiaoyankonling/ssh-mcp)](https://www.npmjs.com/package/@xiaoyankonling/ssh-mcp)
+[![Node Version](https://img.shields.io/node/v/@xiaoyankonling/ssh-mcp)](https://nodejs.org/)
+[![License](https://img.shields.io/github/license/Bianshumeng/ssh-mcp)](./LICENSE)
+[![GitHub Stars](https://img.shields.io/github/stars/Bianshumeng/ssh-mcp?style=social)](https://github.com/Bianshumeng/ssh-mcp/stargazers)
+[![GitHub Forks](https://img.shields.io/github/forks/Bianshumeng/ssh-mcp?style=social)](https://github.com/Bianshumeng/ssh-mcp/forks)
+[![Build Status](https://github.com/Bianshumeng/ssh-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/Bianshumeng/ssh-mcp/actions)
+[![GitHub issues](https://img.shields.io/github/issues/Bianshumeng/ssh-mcp)](https://github.com/Bianshumeng/ssh-mcp/issues)
+
+[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/Bianshumeng/ssh-mcp)](https://archestra.ai/mcp-catalog/Bianshumeng__ssh-mcp)
+
+**SSH MCP Server** is a local Model Context Protocol (MCP) server that exposes SSH control for Linux and Windows systems, enabling LLMs and other MCP clients to execute shell commands securely via SSH.
+
+## Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [Installation](#installation)
+- [Client Setup](#client-setup)
+- [Testing](#testing)
+- [Disclaimer](#disclaimer)
+- [Support](#support)
+
+## Quick Start
+
+- [Install](#installation) SSH MCP Server
+- [Configure](#configuration) SSH MCP Server
+- [Set up](#client-setup) your MCP Client (e.g. Claude Desktop, Cursor, etc)
+- Execute remote shell commands on your Linux or Windows server via natural language
+
+## Features
+
+- MCP-compliant server exposing SSH capabilities
+- Execute shell commands on remote Linux and Windows systems
+- Secure authentication via password or SSH key
+- Local profile configuration via YAML/JSON files
+- Runtime profile management tools (`profiles-list/use/reload/note-update`)
+- Profile notes/tags for operational context
+- Built with TypeScript and the official MCP SDK
+- **Configurable timeout protection** with automatic process abortion
+- **Graceful timeout handling** - attempts to kill hanging processes before closing connections
+
+### Tools
+
+- `exec`: Execute a shell command on the remote server
+  - **Parameters:**
+    - `command` (required): Shell command to execute on the remote SSH server
+    - `description` (optional): Optional description of what this command will do (appended as a comment)
+  - **Timeout Configuration:**
+
+- `sudo-exec`: Execute a shell command with sudo elevation
+  - **Parameters:**
+    - `command` (required): Shell command to execute as root using sudo
+    - `description` (optional): Optional description of what this command will do (appended as a comment)
+  - **Notes:**
+    - Requires `--sudoPassword` to be set for password-protected sudo
+    - Can be disabled by passing the `--disableSudo` flag at startup if sudo access is not needed or not available
+    - For persistent root access, consider using `--suPassword` instead which establishes a root shell
+    - Tool will not be available at all if server is started with `--disableSudo`
+  - **Timeout Configuration:**
+    - Timeout is configured via command line argument `--timeout` (in milliseconds)
+    - Default timeout: 60000ms (1 minute)
+    - When a command times out, the server automatically attempts to abort the running process before closing the connection
+  - **Max Command Length Configuration:**
+    - Max command characters are configured via `--maxChars`
+    - Default: `1000`
+    - No-limit mode: set `--maxChars=none` or any `<= 0` value (e.g. `--maxChars=0`)
+
+- `profiles-list`: List profile summaries (`id/name/host/port/note/tags/active`) with sensitive fields masked
+- `profiles-find`: Find profile candidates by keyword across `id/name/host/user/note/tags`
+- `profiles-use`: Switch active profile at runtime, persist `activeProfile`, and recreate SSH connection on next command
+- `profiles-reload`: Reload profile configuration from disk and validate active profile still exists
+- `profiles-create`: Create profile templates dynamically at runtime (note optional but recommended)
+- `profiles-note-update`: Update and persist a concise profile note
+- `profiles-delete-prepare`: Prepare destructive deletion (creates backup and returns confirmation payload)
+- `profiles-delete-confirm`: Finalize deletion with exact `deleteRequestId + confirmationText`
+
+## Installation
+
+1. **Clone the repository:**
+   ```bash
+  git clone https://github.com/Bianshumeng/ssh-mcp.git
+   cd ssh-mcp
+   ```
+2. **Install dependencies:**
+   ```bash
+   npm install
+   ```
+
+## Client Setup
+
+You can configure your IDE or LLM like Cursor, Windsurf, Claude Desktop to use this MCP Server.
+
+### Profile Mode
+
+This server now runs in profile mode only.
+
+Use `--config` to load multiple SSH profiles from a local YAML/JSON file.
+
+**Parameters:**
+- `config`: Path to profile config file (`.yaml`, `.yml`, `.json`)
+- `profile`: Optional profile id override for startup active profile
+- `timeout`: Optional command timeout override in milliseconds
+- `maxChars`: Optional command length override
+- `disableSudo`: Optional flag to disable `sudo-exec`
+
+**Important:**
+- Legacy startup args (`--host`, `--user`, `--password`, `--key`, etc.) are no longer supported.
+- Dynamic target management is done through profile tools (`profiles-list/find/use/create/delete-*`).
+
+Example:
+
+```bash
+npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --profile=jp-relay
+```
+
+### Profile Configuration Format
+
+The full example is available at `examples/ssh-mcp.profiles.yaml`.
+
+```yaml
+version: 1
+activeProfile: fi-template
+
+defaults:
+  timeout: 120000
+  maxChars: none
+  disableSudo: false
+
+profiles:
+  - id: fi-template
+    name: 芬兰模板机
+    host: fi-template.example.com
+    port: 9900
+    user: root
+    auth:
+      type: password
+      password: "${SSH_TEMPLATE_PASSWORD}"
+    sudoPassword: "${SSH_TEMPLATE_SUDO_PASSWORD}"
+    note: "模板维护机，做 cloud-init 和预装验证"
+    tags: [template, fi]
+```
+
+Notes:
+- `${ENV_VAR}` placeholders are expanded at load time
+- `auth.type=password` requires `auth.password`
+- `auth.type=key` requires `auth.keyPath` and the file must exist
+- `activeProfile` must match one of `profiles[].id`
+- Profile list output and tool responses never expose plaintext passwords
+
+### Dynamic Template Management Workflow
+
+1. Create template at runtime:
+   - call `profiles-create`
+   - by default, created profile is activated immediately
+2. Keep note short and precise:
+   - if `note` is omitted, tool can derive a concise note from `contextSummary`
+3. Safe deletion (two-step):
+   - call `profiles-delete-prepare` first
+   - review returned profile + backup path + confirmation text with user
+   - only then call `profiles-delete-confirm`
+
+`profiles-delete-confirm` requires exact confirmation text in the form:
+
+```text
+DELETE <profileId>
+```
+
+This guards against accidental profile removal and ensures a backup exists before delete.
+
+### Claude Code
+
+You can add this MCP server to Claude Code using the `claude mcp add` command. This is the recommended method for Claude Code.
+
+**Basic Installation:**
+
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=/path/to/ssh-mcp.profiles.yaml
+```
+
+**Installation Examples:**
+
+**With Config File:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml
+```
+
+**With Startup Profile Override:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --profile=jp-relay
+```
+
+**With Custom Timeout and No Character Limit:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --timeout=120000 --maxChars=none
+```
+
+**With Sudo Tool Disabled:**
+```bash
+claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml --disableSudo
+```
+
+**Installation Scopes:**
+
+You can specify the scope when adding the server:
+
+- **Local scope** (default): For personal use in the current project
+  ```bash
+  claude mcp add --transport stdio ssh-mcp --scope local -- npx -y @xiaoyankonling/ssh-mcp -- --config=/path/to/ssh-mcp.profiles.yaml
+  ```
+
+- **Project scope**: Share with your team via `.mcp.json` file
+  ```bash
+  claude mcp add --transport stdio ssh-mcp --scope project -- npx -y @xiaoyankonling/ssh-mcp -- --config=./config/ssh-mcp.profiles.yaml
+  ```
+
+- **User scope**: Available across all your projects
+  ```bash
+  claude mcp add --transport stdio ssh-mcp --scope user -- npx -y @xiaoyankonling/ssh-mcp -- --config=/absolute/path/to/ssh-mcp.profiles.yaml
+  ```
+
+
+**Verify Installation:**
+
+After adding the server, restart Claude Code and ask Cascade to execute a command:
+```
+"Can you run 'ls -la' on the remote server?"
+```
+
+For more information about MCP in Claude Code, see the [official documentation](https://docs.claude.com/en/docs/claude-code/mcp).
+
+## Testing
+
+You can use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) for visual debugging of this MCP Server.
+
+```sh
+npm run inspect
+```
+
+## Disclaimer
+
+SSH MCP Server is provided under the [MIT License](./LICENSE). Use at your own risk. This project is not affiliated with or endorsed by any SSH or MCP provider.
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guidelines](./CONTRIBUTING.md) for more information.
+
+## Code of Conduct
+
+This project follows a [Code of Conduct](./CODE_OF_CONDUCT.md) to ensure a welcoming environment for everyone.
+
+## Support
+
+If you find SSH MCP Server helpful, consider starring the repository or contributing! Pull requests and feedback are welcome. 

package/build/cli/args.js

@@ -0,0 +1,75 @@
+import path from 'path';
+import { DEFAULT_MAX_CHARS, DEFAULT_TIMEOUT_MS, parseMaxChars } from '../ssh/command-utils.js';
+const LEGACY_ARG_KEYS = [
+    'host',
+    'user',
+    'port',
+    'password',
+    'key',
+    'suPassword',
+    'sudoPassword',
+];
+export function parseArgv(argv = process.argv.slice(2)) {
+    const config = {};
+    for (const arg of argv) {
+        if (!arg.startsWith('--'))
+            continue;
+        const equalIndex = arg.indexOf('=');
+        if (equalIndex === -1) {
+            config[arg.slice(2)] = null;
+            continue;
+        }
+        config[arg.slice(2, equalIndex)] = arg.slice(equalIndex + 1);
+    }
+    return config;
+}
+function normalizeOptionalString(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function parsePositiveInt(input, fallback) {
+    if (typeof input !== 'string' || input.trim() === '')
+        return fallback;
+    const parsed = Number.parseInt(input, 10);
+    if (Number.isNaN(parsed) || parsed <= 0)
+        return fallback;
+    return parsed;
+}
+function hasLegacyTargetArgs(config) {
+    return LEGACY_ARG_KEYS.some((key) => config[key] !== undefined);
+}
+export function validateConfig(config) {
+    const configPath = normalizeOptionalString(config.config);
+    if (!configPath) {
+        throw new Error('Configuration error:\nMissing required --config=<path>. Legacy --host/--user startup is no longer supported.');
+    }
+    if (hasLegacyTargetArgs(config)) {
+        throw new Error('Configuration error:\nLegacy target args (--host/--user/--password/--key/...) are no longer supported. Use --config and manage targets via profiles tools.');
+    }
+}
+export function resolveRuntimeOptions(config, defaults) {
+    const timeoutMs = parsePositiveInt(config.timeout, defaults?.timeout ?? DEFAULT_TIMEOUT_MS);
+    const maxCharsSource = config.maxChars ?? defaults?.maxChars;
+    const maxChars = parseMaxChars(maxCharsSource, DEFAULT_MAX_CHARS);
+    const disableSudo = config.disableSudo !== undefined
+        ? true
+        : Boolean(defaults?.disableSudo ?? false);
+    return {
+        timeoutMs,
+        maxChars,
+        disableSudo,
+    };
+}
+export function determineStartupMode(config) {
+    validateConfig(config);
+    const configPath = normalizeOptionalString(config.config);
+    const profileIdOverride = normalizeOptionalString(config.profile);
+    return {
+        mode: 'profile',
+        configPath: path.resolve(configPath),
+        profileIdOverride,
+        runtime: resolveRuntimeOptions(config),
+    };
+}

package/build/config/loader.js

@@ -0,0 +1,138 @@
+import { access, readFile, writeFile } from 'fs/promises';
+import path from 'path';
+import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import { profilesConfigSchema, } from './types.js';
+const ENV_PATTERN = /\$\{([A-Z0-9_]+)\}/g;
+function inferFormat(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.json')
+        return 'json';
+    if (ext === '.yaml' || ext === '.yml')
+        return 'yaml';
+    throw new Error(`Unsupported config file extension: ${ext || '<none>'}. Use .yaml/.yml/.json`);
+}
+function assertObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('Config root must be an object');
+    }
+}
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function expandEnvString(input) {
+    return input.replace(ENV_PATTERN, (_, envName) => {
+        const envValue = process.env[envName];
+        if (envValue === undefined) {
+            throw new Error(`Missing required environment variable: ${envName}`);
+        }
+        return envValue;
+    });
+}
+function expandEnv(value) {
+    if (typeof value === 'string') {
+        return expandEnvString(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => expandEnv(item));
+    }
+    if (value && typeof value === 'object') {
+        const expanded = {};
+        for (const [key, item] of Object.entries(value)) {
+            expanded[key] = expandEnv(item);
+        }
+        return expanded;
+    }
+    return value;
+}
+function ensureActiveProfileExists(config) {
+    const exists = config.profiles.some((profile) => profile.id === config.activeProfile);
+    if (!exists) {
+        throw new Error(`activeProfile "${config.activeProfile}" does not exist in profiles`);
+    }
+}
+export function resolveKeyPath(keyPath, configFilePath) {
+    if (path.isAbsolute(keyPath)) {
+        return keyPath;
+    }
+    const baseDir = path.dirname(configFilePath);
+    return path.resolve(baseDir, keyPath);
+}
+async function validateProfileAuthFields(config, filePath) {
+    for (const profile of config.profiles) {
+        if (profile.auth.type === 'password') {
+            if (!profile.auth.password || profile.auth.password.trim() === '') {
+                throw new Error(`Profile "${profile.id}" requires auth.password`);
+            }
+        }
+        if (profile.auth.type === 'key') {
+            if (!profile.auth.keyPath || profile.auth.keyPath.trim() === '') {
+                throw new Error(`Profile "${profile.id}" requires auth.keyPath`);
+            }
+            const resolvedPath = resolveKeyPath(profile.auth.keyPath, filePath);
+            try {
+                await access(resolvedPath);
+            }
+            catch {
+                throw new Error(`Profile "${profile.id}" keyPath does not exist: ${resolvedPath}`);
+            }
+        }
+    }
+}
+export async function validateRawProfilesConfig(rawConfig, filePath) {
+    const expandedConfig = expandEnv(deepClone(rawConfig));
+    const parsedConfig = profilesConfigSchema.parse(expandedConfig);
+    ensureActiveProfileExists(parsedConfig);
+    await validateProfileAuthFields(parsedConfig, filePath);
+    return parsedConfig;
+}
+function parseRawContent(content, format) {
+    if (format === 'json') {
+        const parsed = JSON.parse(content);
+        assertObject(parsed);
+        return parsed;
+    }
+    const parsed = parseYaml(content);
+    assertObject(parsed);
+    return parsed;
+}
+export async function loadProfilesConfig(filePath) {
+    const format = inferFormat(filePath);
+    const content = await readFile(filePath, 'utf8');
+    const rawConfig = parseRawContent(content, format);
+    const parsedConfig = await validateRawProfilesConfig(rawConfig, filePath);
+    return {
+        filePath,
+        format,
+        config: parsedConfig,
+        rawConfig,
+    };
+}
+function serializeRawConfig(rawConfig, format) {
+    if (format === 'json') {
+        return JSON.stringify(rawConfig, null, 2) + '\n';
+    }
+    return stringifyYaml(rawConfig);
+}
+export async function saveRawProfilesConfig(loaded) {
+    const output = serializeRawConfig(loaded.rawConfig, loaded.format);
+    await writeFile(loaded.filePath, output, 'utf8');
+}
+export function profileSummary(profile, activeProfileId) {
+    const authSummary = profile.auth.type === 'password'
+        ? { type: 'password', password: '***' }
+        : {
+            type: 'key',
+            keyPath: path.basename(profile.auth.keyPath),
+        };
+    return {
+        id: profile.id,
+        name: profile.name,
+        host: profile.host,
+        port: profile.port,
+        user: profile.user,
+        note: profile.note ?? '',
+        tags: profile.tags ?? [],
+        auth: authSummary,
+        active: profile.id === activeProfileId,
+    };
+}

package/build/config/types.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+const intFromStringSchema = z.string().regex(/^-?\d+$/).transform((value) => Number.parseInt(value, 10));
+const intLikeSchema = z.union([
+    z.number().int(),
+    intFromStringSchema,
+]).transform((value) => value);
+const positiveIntLikeSchema = intLikeSchema.refine((value) => value > 0, { message: 'must be a positive integer' });
+const booleanLikeSchema = z.union([z.boolean(), z.string()]).transform((value, ctx) => {
+    if (typeof value === 'boolean')
+        return value;
+    const lowered = value.trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(lowered))
+        return true;
+    if (['false', '0', 'no', 'off'].includes(lowered))
+        return false;
+    ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: 'must be a boolean-like value',
+    });
+    return z.NEVER;
+});
+export const maxCharsConfigSchema = z.union([
+    z.literal('none'),
+    intLikeSchema,
+]);
+const passwordAuthSchema = z.object({
+    type: z.literal('password'),
+    password: z.string().min(1, 'password auth requires a non-empty password'),
+}).strict();
+const keyAuthSchema = z.object({
+    type: z.literal('key'),
+    keyPath: z.string().min(1, 'key auth requires a non-empty keyPath'),
+}).strict();
+export const profileAuthSchema = z.discriminatedUnion('type', [
+    passwordAuthSchema,
+    keyAuthSchema,
+]);
+export const profileDefaultsSchema = z.object({
+    timeout: positiveIntLikeSchema.optional(),
+    maxChars: maxCharsConfigSchema.optional(),
+    disableSudo: booleanLikeSchema.optional(),
+}).default({});
+const portSchema = positiveIntLikeSchema.refine((value) => value <= 65535, {
+    message: 'port must be between 1 and 65535',
+});
+export const profileSchema = z.object({
+    id: z.string().min(1, 'profile id is required'),
+    name: z.string().min(1, 'profile name is required'),
+    host: z.string().min(1, 'profile host is required'),
+    port: portSchema.default(22),
+    user: z.string().min(1, 'profile user is required'),
+    auth: profileAuthSchema,
+    suPassword: z.string().min(1).optional(),
+    sudoPassword: z.string().min(1).optional(),
+    note: z.string().default(''),
+    tags: z.array(z.string()).default([]),
+}).strict();
+export const profilesConfigSchema = z.object({
+    version: z.literal(1),
+    activeProfile: z.string().min(1, 'activeProfile is required'),
+    defaults: profileDefaultsSchema.optional().default({}),
+    profiles: z.array(profileSchema).min(1, 'at least one profile is required'),
+}).strict().superRefine((value, ctx) => {
+    const seenIds = new Set();
+    for (const profile of value.profiles) {
+        if (seenIds.has(profile.id)) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message: `duplicate profile id: ${profile.id}`,
+                path: ['profiles'],
+            });
+        }
+        seenIds.add(profile.id);
+    }
+});