MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

S
Ssh MCP
by @Bianshumeng
GitHub Repo(1 stars)

MCP server by Bianshumeng

Created 2/15/2026
Updated about 9 hours ago
README
View Source
Repository documentation and setup instructions

SSH MCP Server

NPM Version Downloads Node Version License GitHub Stars GitHub Forks Build Status GitHub issues

Trust Score

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

  • Install SSH MCP Server
  • Configure SSH MCP Server
  • Set up 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/find/use/reload/note-update/profiles-test)
  • 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)
      • timeoutMs (optional): Per-command timeout override in milliseconds
    • 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)
      • timeoutMs (optional): Per-command timeout override in milliseconds
    • 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-test: Test TCP connectivity, SSH handshake, and authentication for a profile

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

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:

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.

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. Validate target quickly:
    • call profiles-test to verify TCP/SSH/auth before executing commands
  4. 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:

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:

claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=/path/to/ssh-mcp.profiles.yaml

Installation Examples:

With Config File:

claude mcp add --transport stdio ssh-mcp -- npx -y @xiaoyankonling/ssh-mcp -- --config=./examples/ssh-mcp.profiles.yaml

With Startup Profile Override:

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:

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:

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

    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

    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

    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.

Testing

You can use the MCP Inspector for visual debugging of this MCP Server.

npm run inspect

Disclaimer

SSH MCP Server is provided under the MIT 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 for more information.

Code of Conduct

This project follows a Code of Conduct 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.

Quick Setup
Installation guide for this server

Install Package (if required)

npx @modelcontextprotocol/server-ssh-mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "bianshumeng-ssh-mcp": { "command": "npx", "args": [ "bianshumeng-ssh-mcp" ] } } }