Skip to content
Back to search

mcp-ssh

A Model Context Protocol (MCP) server for managing and controlling SSH connections.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aiondadotcom--mcp-ssh/badge.svg)](/listings/aiondadotcom--mcp-ssh)

HTML

<a href="/listings/aiondadotcom--mcp-ssh"><img src="/api/listings/aiondadotcom--mcp-ssh/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

MCP Bundle Installation (Recommended)

The easiest way to install MCP SSH Agent is as an MCP Bundle:

1. Download the latest `mcp-ssh-*.mcpb` file from the [GitHub releases page](https://github.com/aiondadotcom/mcp-ssh/releases) 2. Double-click the `.mcpb` file to install it in Claude Desktop

> The bundle format was previously called a Desktop Extension and used the `.dxt` > extension. v1.3.9 shipped both files during the transition; later releases carry > `.mcpb` only. If your Claude Desktop is old enough to reject a `.mcpb` file, > update it or use one of the installation methods below. 3. The SSH tools will be automatically available in your conversations with Claude

Alternative Installation Methods

Installation via npx

npx @aiondadotcom/mcp-ssh

Manual Claude Desktop Configuration

To use this MCP server with Claude Desktop using manual configuration, add the following to your MCP settings file:

**On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` **On Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "mcp-ssh": {
      "command": "npx",
      "args": ["@aiondadotcom/mcp-ssh"]
    }
  }
}

After adding this configuration, restart Claude Desktop. The SSH tools will be available for use in your conversations with Claude.

Global Installation

npm install -g @aiondadotcom/mcp-ssh

Local Development

git clone https://github.com/aiondadotcom/mcp-ssh.git
cd mcp-ssh
npm install   # also compiles src/ -> dist/
npm start

The server is TypeScript under `src/`; `npm install` builds it. After editing sources run `npm run build` (or `npm test`, which reads `src/` directly).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 732 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP SSH Agent
  2. [![Tests](https://github.com/AiondaDotCom/mcp-ssh/actions/workflows/test.yml/badge.svg)](https://github.com/AiondaDotCom/mcp-ssh/actions/workflows/test.yml)
  3. A Model Context Protocol (MCP) server for managing and controlling SSH connections. This server integrates seamlessly with Claude Desktop and other MCP-compatible clients to provide AI-powered SSH operations.
  4. ## Overview
  5. This MCP server provides SSH operations through a clean, standardized interface that can be used by MCP-compatible language models like Claude Desktop. The server automatically discovers SSH hosts from your `~/.ssh/config` and `~/.ssh/known_hosts` files and executes commands using native SSH tools for maximum reliability.
  6. ## Quick Start
  7. ### MCP Bundle Installation (Recommended)
  8. The easiest way to install MCP SSH Agent is as an MCP Bundle:
  9. 1. Download the latest `mcp-ssh-*.mcpb` file from the [GitHub releases page](https://github.com/aiondadotcom/mcp-ssh/releases)
  10. 2. Double-click the `.mcpb` file to install it in Claude Desktop
  11. > The bundle format was previously called a Desktop Extension and used the `.dxt`
  12. > extension. v1.3.9 shipped both files during the transition; later releases carry
  13. > `.mcpb` only. If your Claude Desktop is old enough to reject a `.mcpb` file,
  14. > update it or use one of the installation methods below.
  15. 3. The SSH tools will be automatically available in your conversations with Claude
  16. ### Alternative Installation Methods
  17. #### Installation via npx
  18. ```bash
  19. npx @aiondadotcom/mcp-ssh
  20. ```
  21. #### Manual Claude Desktop Configuration
  22. To use this MCP server with Claude Desktop using manual configuration, add the following to your MCP settings file:
  23. **On macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  24. **On Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
  25. ```json
  26. {
  27. "mcpServers": {
  28. "mcp-ssh": {
  29. "command": "npx",
  30. "args": ["@aiondadotcom/mcp-ssh"]
  31. }
  32. }
  33. }
  34. ```
  35. After adding this configuration, restart Claude Desktop. The SSH tools will be available for use in your conversations with Claude.
  36. #### Global Installation
  37. ```bash
  38. npm install -g @aiondadotcom/mcp-ssh
  39. ```
  40. #### Local Development
  41. ```bash
  42. git clone https://github.com/aiondadotcom/mcp-ssh.git
  43. cd mcp-ssh
  44. npm install # also compiles src/ -> dist/
  45. npm start
  46. ```
  47. The server is TypeScript under `src/`; `npm install` builds it. After editing sources run
  48. `npm run build` (or `npm test`, which reads `src/` directly).
  49. ## Example Usage
  50. ![MCP SSH Agent Example](doc/example.png)
  51. The screenshot above shows the MCP SSH Agent in action, demonstrating how it integrates with MCP-compatible clients to provide seamless SSH operations.
  52. ### Integration with Claude
  53. ![Claude MCP Integration](doc/Claude.png)
  54. This screenshot demonstrates the MCP SSH Agent integrated with Claude, showing how the AI assistant can directly manage SSH connections and execute remote commands through the MCP protocol.
  55. ## Key Features
  56. - **Reliable SSH**: Uses native `ssh`/`scp` commands instead of JavaScript SSH libraries
  57. - **Automatic Discovery**: Finds hosts from SSH config and known_hosts files
  58. - **Full SSH Support**: Works with SSH agents, keys, and all authentication methods
  59. - **Password Authentication**: Supports password-based SSH login and key passphrases via `@password` annotation — passwords never leave your machine
  60. - **File Operations**: Upload and download files using `scp`
  61. - **Batch Commands**: Execute multiple commands in sequence
  62. - **Error Handling**: Comprehensive error reporting with timeouts
  63. ## Functions
  64. The agent provides the following MCP tools:
  65. 1. **listKnownHosts()** - Lists all known SSH hosts, prioritizing entries from ~/.ssh/config first, then additional hosts from ~/.ssh/known_hosts
  66. 2. **runRemoteCommand(hostAlias, command)** - Executes a command on a remote host using `ssh`
  67. 3. **getHostInfo(hostAlias)** - Returns detailed configuration for a specific host
  68. 4. **checkConnectivity(hostAlias)** - Tests SSH connectivity to a host
  69. 5. **uploadFile(hostAlias, localPath, remotePath)** - Uploads a file to the remote host using `scp`
  70. 6. **downloadFile(hostAlias, remotePath, localPath)** - Downloads a file from the remote host using `scp`
  71. 7. **runCommandBatch(hostAlias, commands)** - Executes multiple commands sequentially
  72. ## Configuration Examples
  73. ### Claude Desktop Integration
  74. Here's how your Claude Desktop configuration should look:
  75. ```json
  76. {
  77. "mcpServers": {
  78. "mcp-ssh": {
  79. "command": "npx",
  80. "args": ["@aiondadotcom/mcp-ssh"]
  81. }
  82. }
  83. }
  84. ```
  85. ### Manual Server Configuration
  86. If you prefer to run the server manually or integrate it with other MCP clients:
  87. ```json
  88. {
  89. "servers": {
  90. "mcp-ssh": {
  91. "command": "npx",
  92. "args": ["@aiondadotcom/mcp-ssh"]
  93. }
  94. }
  95. }
  96. ```
  97. ## Requirements
  98. - Node.js 20 or higher
  99. - SSH client installed (`ssh` and `scp` commands available)
  100. - SSH configuration files (`~/.ssh/config` and `~/.ssh/known_hosts`)
  101. ## Usage with Claude Desktop
  102. Once configured, you can ask Claude to help you with SSH operations like:
  103. - "List all my SSH hosts"
  104. - "Check connectivity to my production server"
  105. - "Run a command on my web server"
  106. - "Upload this file to my remote server"
  107. - "Download logs from my application server"
  108. Claude will use the MCP SSH tools to perform these operations safely and efficiently.
  109. ## Usage
  110. The agent runs as a Model Context Protocol server over STDIO. When installed via npm, you can use it directly:
  111. ```bash
  112. # Run via npx (recommended)
  113. npx @aiondadotcom/mcp-ssh
  114. # Or if installed globally
  115. mcp-ssh
  116. # For development - run with debug output
  117. npm start
  118. ```
  119. The server communicates via clean JSON over STDIO, making it perfect for MCP clients like Claude Desktop.
  120. ## Advanced Configuration
  121. ### Environment Variables
  122. - `MCP_SILENT=true` - Disable debug output (automatically set when used as MCP server)
  123. ### SSH Configuration
  124. The agent reads from standard SSH configuration files:
  125. - `~/.ssh/config` - SSH client configuration (supports Include directives)
  126. - `~/.ssh/known_hosts` - Known host keys
  127. Make sure your SSH keys are properly configured and accessible via SSH agent or key files.
  128. #### Password Authentication
  129. For hosts that require password-based authentication (common with network infrastructure like switches and routers), you can store the password directly in your `~/.ssh/config` using a special comment annotation:
  130. ```ssh-config
  131. Host myrouter
  132. HostName 192.168.1.1
  133. User admin
  134. # @password:yourSecretPassword
  135. Host myserver
  136. HostName 10.0.0.5
  137. User deploy
  138. IdentityFile ~/.ssh/id_rsa
  139. # @password:myKeyPassphrase
  140. ```
  141. **How it works:**
  142. - The `# @password:` annotation is read **locally** by the MCP server — the password **never** reaches the AI model or any cloud provider
  143. - Works for both login passwords and SSH key passphrases
  144. - The password is split at the first `:`, so passwords containing `:` are supported
  145. - When listing hosts, only `passwordAuth: true` is shown — the actual password is never exposed
  146. **Security requirements:**
  147. - Your SSH config file **must** have `600` permissions when using `@password` annotations
  148. - The MCP server will refuse to start if the file permissions are too open
  149. - Fix with: `chmod 600 ~/.ssh/config`
  150. #### Include Directive Support
  151. The MCP SSH Agent fully supports SSH `Include` directives to organize your configuration across multiple files. However, there's an important SSH bug to be aware of:
  152. **⚠️ SSH Include Directive Bug Warning**
  153. SSH has a configuration parsing bug where `Include` statements **must be placed at the beginning** of your `~/.ssh/config` file to work correctly. If placed at the end, SSH will read them but won't properly apply the included configurations.
  154. **✅ Correct placement (at the beginning):**
  155. ```ssh-config
  156. # ~/.ssh/config
  157. Include ~/.ssh/config.d/*
  158. Include ~/.ssh/work-hosts
  159. # Global settings
  160. ServerAliveInterval 55
  161. # Host definitions
  162. Host myserver
  163. HostName example.com
  164. ```
  165. **❌ Incorrect placement (at the end) - won't work:**
  166. ```ssh-config
  167. # ~/.ssh/config
  168. # Global settings
  169. ServerAliveInterval 55
  170. # Host definitions
  171. Host myserver
  172. HostName example.com
  173. # These Include statements won't work properly due to SSH bug:
  174. Include ~/.ssh/config.d/*
  175. Include ~/.ssh/work-hosts
  176. ```
  177. The MCP SSH Agent correctly processes `Include` directives regardless of their placement in the file, so you'll get full host discovery even if SSH itself has issues with your configuration.
  178. #### Example ~/.ssh/config
  179. Here's an example SSH configuration file that demonstrates various connection scenarios including Include directives and `@password` annotations for password-based authentication:
  180. ```ssh-config
  181. # Include directives must be at the beginning due to SSH bug
  182. Include ~/.ssh/config.d/*
  183. Include ~/.ssh/work-servers
  184. # Global settings - keep connections alive
  185. ServerAliveInterval 55
  186. # Production server with jump host
  187. Host prod
  188. Hostname 203.0.113.10
  189. Port 22022
  190. User deploy
  191. IdentityFile ~/.ssh/id_prod_rsa
  192. # Root access to production (separate entry)
  193. Host root@prod
  194. Hostname 203.0.113.10
  195. Port 22022
  196. User root
  197. IdentityFile ~/.ssh/id_prod_rsa
  198. # Router with password authentication (no SSH key)
  199. Host router
  200. Hostname 192.168.1.1
  201. User admin
  202. # @password:cQbG0q@019TAoehZel7V
  203. # Archive server accessed through production jump host
  204. Host archive
  205. Hostname 2001:db8:1f0:cafe::1
  206. Port 22077
  207. User archive-user
  208. ProxyJump prod
  209. # Web servers with specific configurations
  210. Host web1.example.com
  211. Hostname 198.51.100.15
  212. Port 22022
  213. User root
  214. IdentityFile ~/.ssh/id_ed25519
  215. Host web2.example.com
  216. Hostname 198.51.100.25
  217. Port 22022
  218. User root
  219. IdentityFile ~/.ssh/id_ed25519
  220. # Database server with custom key and passphrase-protected key
  221. Host database
  222. Hostname 203.0.113.50
  223. Port 22077
  224. User dbadmin
  225. IdentityFile ~/.ssh/id_database_rsa
  226. IdentitiesOnly yes
  227. # @password:U1Jqn=NoKdELYn&h1jVT
  228. # Mail servers (password auth, no SSH key)
  229. Host mail1
  230. Hostname 198.51.100.88
  231. Port 22078
  232. User mailuser
  233. # @password:7iBiV8lyoq*zANv46ALD
  234. Host root@mail1
  235. Hostname 198.51.100.88
  236. Port 22078
  237. User root
  238. # @password:MRDHI2h!zhhN=ZJIxWzH
  239. # Monitoring server
  240. Host monitor
  241. Hostname 203.0.113.100
  242. Port 22077
  243. User monitoring
  244. IdentityFile ~/.ssh/id_monitor_ed25519
  245. IdentitiesOnly yes
  246. # Load balancers
  247. Host lb-a
  248. Hostname 198.51.100.200
  249. Port 22077
  250. User root
  251. Host lb-b
  252. Hostname 198.51.100.201
  253. Port 22077
  254. User root
  255. # One host reachable under several aliases - both names work
  256. Host docker-lxc hlab
  257. Hostname 10.9.0.105
  258. User root
  259. ```
  260. This configuration demonstrates:
  261. - **Global settings**: `ServerAliveInterval` to keep connections alive
  262. - **Custom ports**: Non-standard SSH ports for security
  263. - **Multiple users**: Different user accounts for the same host (e.g., `prod` and `root@prod`)
  264. - **Multiple aliases**: One host declared under several names (e.g., `docker-lxc hlab`) — reachable under each
  265. - **Jump hosts**: Using `ProxyJump` to access servers through bastion hosts
  266. - **IPv6 addresses**: Modern networking support
  267. - **Identity files**: Specific SSH keys for different servers
  268. - **Security options**: `IdentitiesOnly yes` to use only specified keys
  269. - **Password authentication**: `# @password:` annotations for devices without SSH key support (e.g., routers, switches) or for passphrase-protected keys
  270. #### Which Hosts Are Discovered
  271. `listKnownHosts()` reports every connectable host it finds in `~/.ssh/config` (including
  272. everything pulled in through `Include`), followed by any additional hostnames from
  273. `~/.ssh/known_hosts`. Three rules decide what counts as connectable:
  274. **Multi-alias blocks work under every alias.** `Host` takes a list of patterns, not a single
  275. name, so a block can declare several aliases at once:
  276. ```ssh-config
  277. Host docker-lxc hlab
  278. Hostname 10.9.0.105
  279. User root
  280. ```
  281. Both `docker-lxc` and `hlab` reach this host. The response carries the full list in an
  282. `aliases` field, while `alias` holds the first one.
  283. **Defaults blocks are skipped.** A block whose patterns are only wildcards and negations
  284. sets defaults for other hosts — it is not something you can connect to, so it is left out
  285. of the host list:
  286. ```ssh-config
  287. Host *
  288. ServerAliveInterval 55
  289. Host * !bastion # "everything except bastion" — a defaults block, not a host
  290. User deploy
  291. IdentityFile ~/.ssh/id_deploy
  292. ```
  293. (OpenSSH lets you negate a pattern with `!`. A negated match vetoes the whole line, which
  294. is why negation only makes sense as an exception to a wildcard.)
  295. **Hosts without a `Hostname` are skipped**, since there is nothing to connect to.
  296. Plain top-level directives such as a bare `ServerAliveInterval 55` are configuration for
  297. `ssh` itself and are ignored by host discovery — `ssh` still applies them, because every
  298. operation runs through your system's `ssh` binary.
  299. #### How MCP SSH Agent Uses Your Configuration
  300. The MCP SSH agent automatically discovers and uses your SSH configuration:
  301. 1. **Host Discovery**: Every connectable host from `~/.ssh/config` is available — see the rules above
  302. 2. **Native SSH**: Uses your system's `ssh` command, so all config options work
  303. 3. **Authentication**: Respects your SSH agent, key files, and authentication settings
  304. 4. **Jump Hosts**: Supports complex proxy chains and bastion host setups
  305. 5. **Port Forwarding**: Can work with custom ports and connection options
  306. **Example Usage with Claude Desktop:**
  307. - "List my SSH hosts" → Shows all configured hosts including `prod`, `archive`, `web1.example.com`, etc.
  308. - "Connect to archive server" → Uses the ProxyJump configuration automatically
  309. - "Run 'df -h' on web1.example.com" → Connects with the correct user, port, and key
  310. - "Upload file to database server" → Uses the specific identity file and port configuration
  311. ## Troubleshooting
  312. ### Common Issues
  313. 1. **Command not found**: Ensure `ssh` and `scp` are installed and in your PATH
  314. 2. **Permission denied**: Check SSH key permissions and SSH agent
  315. 3. **Host not found**: Verify the host exists in `~/.ssh/config` or `~/.ssh/known_hosts`, and that its block has a `Hostname` — blocks without one, and pure defaults blocks such as `Host *`, are not connectable hosts. See [Which Hosts Are Discovered](#which-hosts-are-discovered)
  316. 4. **Connection timeout**: Check network connectivity and firewall settings
  317. 5. **Windows: every command fails with exit 255 and empty output**: Fixed after 1.3.8. Earlier versions inherit a stripped environment from the MCP host that omits `%ProgramData%`, which Win32-OpenSSH needs at startup. Upgrade, or add `"ProgramData": "C:\\ProgramData"` to the `env` block of your client configuration
  318. ### Debug Mode
  319. Run with debug output to see detailed operation logs:
  320. ```bash
  321. # Enable debug mode
  322. MCP_SILENT=false npx @aiondadotcom/mcp-ssh
  323. ```
  324. ## SSH Key Setup Guide
  325. For the MCP SSH Agent to work properly, you need to set up SSH key authentication. Here's a complete guide:
  326. ### 1. Creating SSH Keys
  327. Generate a new SSH key pair (use Ed25519 for better security):
  328. ```bash
  329. # Generate Ed25519 key (recommended)
  330. ssh-keygen -t ed25519 -C "your-email@example.com"
  331. # Or generate RSA key (if Ed25519 is not supported)
  332. ssh-keygen -t rsa -b 4096 -C "your-email@example.com"
  333. ```
  334. **Important**: When prompted for a passphrase, **leave it empty** (press Enter). The MCP SSH Agent cannot handle password-protected keys as it runs non-interactively.
  335. ```
  336. Enter passphrase (empty for no passphrase): [Press Enter]
  337. Enter same passphrase again: [Press Enter]
  338. ```
  339. This creates two files:
  340. - `~/.ssh/id_ed25519` (private key) - Keep this secret!
  341. - `~/.ssh/id_ed25519.pub` (public key) - This gets copied to servers
  342. ### 2. Installing Public Key on Remote Servers
  343. Copy your public key to the remote server's authorized_keys file:
  344. ```bash
  345. # Method 1: Using ssh-copy-id (easiest)
  346. ssh-copy-id user@hostname
  347. # Method 2: Manual copy
  348. cat ~/.ssh/id_ed25519.pub | ssh user@hostname "mkdir -p ~/.ssh && cat >> ~/.ssh/authorized_keys"
  349. # Method 3: Copy and paste manually
  350. cat ~/.ssh/id_ed25519.pub
  351. # Then SSH to the server and paste into ~/.ssh/authorized_keys
  352. ```
  353. ### 3. Server-Side SSH Configuration
  354. To enable secure key-only authentication on your SSH servers, edit `/etc/ssh/sshd_config`:
  355. ```bash
  356. # Edit SSH daemon configuration
  357. sudo nano /etc/ssh/sshd_config
  358. ```
  359. Add or modify these settings:
  360. ```ssh-config
  361. # Enable public key authentication
  362. PubkeyAuthentication yes
  363. AuthorizedKeysFile .ssh/authorized_keys
  364. # Disable password authentication (security best practice)
  365. PasswordAuthentication no
  366. ChallengeResponseAuthentication no
  367. UsePAM no
  368. # Root login options (choose one):
  369. # Option 1: Allow root login with SSH keys only (recommended for admin access)
  370. PermitRootLogin prohibit-password
  371. # Option 2: Completely disable root login (most secure, but less flexible)
  372. # PermitRootLogin no
  373. # Optional: Restrict SSH to specific users
  374. AllowUsers deploy root admin
  375. # Optional: Change default port for security
  376. Port 22022
  377. ```
  378. After editing, restart the SSH service:
  379. ```bash
  380. # On Ubuntu/Debian
  381. sudo systemctl restart ssh
  382. # On CentOS/RHEL/Fedora
  383. sudo systemctl restart sshd
  384. # On macOS
  385. sudo launchctl unload /System/Library/LaunchDaemons/ssh.plist
  386. sudo launchctl load /System/Library/LaunchDaemons/ssh.plist
  387. ```
  388. ### 4. Setting Correct Permissions
  389. SSH is very strict about file permissions. Set them correctly:
  390. **On your local machine:**
  391. ```bash
  392. chmod 700 ~/.ssh
  393. chmod 600 ~/.ssh/id_ed25519
  394. chmod 644 ~/.ssh/id_ed25519.pub
  395. chmod 644 ~/.ssh/config
  396. chmod 644 ~/.ssh/known_hosts
  397. ```
  398. **On the remote server:**
  399. ```bash
  400. chmod 700 ~/.ssh
  401. chmod 600 ~/.ssh/authorized_keys
  402. ```
  403. ### 5. Testing SSH Key Authentication
  404. Test your connection before using with MCP SSH Agent:
  405. ```bash
  406. # Test connection
  407. ssh -i ~/.ssh/id_ed25519 user@hostname
  408. # Test with verbose output for debugging
  409. ssh -v -i ~/.ssh/id_ed25519 user@hostname
  410. # Test specific configuration
  411. ssh -F ~/.ssh/config hostname
  412. ```
  413. ### 6. Multiple Keys for Different Servers
  414. You can create different keys for different servers:
  415. ```bash
  416. # Create specific keys
  417. ssh-keygen -t ed25519 -f ~/.ssh/id_production -C "production-server"
  418. ssh-keygen -t ed25519 -f ~/.ssh/id_staging -C "staging-server"
  419. ```
  420. Then configure them in `~/.ssh/config`:
  421. ```ssh-config
  422. Host production
  423. Hostname prod.example.com
  424. User deploy
  425. IdentityFile ~/.ssh/id_production
  426. IdentitiesOnly yes
  427. Host staging
  428. Hostname staging.example.com
  429. User deploy
  430. IdentityFile ~/.ssh/id_staging
  431. IdentitiesOnly yes
  432. ```
  433. ## Threat Model and Trust Boundaries
  434. MCP SSH Agent gives an LLM the ability to drive `ssh` and `scp` on your behalf. Before using it, it is important to understand what an attacker who controls the LLM's instructions (for example via **prompt injection** through web pages, e‑mails, repository files, or another MCP server's output) can do:
  435. - **`runRemoteCommand` is full remote code execution on every host you have configured.** If your `~/.ssh/config` contains an entry for `production`, the LLM can run arbitrary commands as that user on that host. This is the tool's purpose, not a bug — but it means you should only configure hosts that you are willing to let the LLM touch, and prefer least-privilege accounts.
  436. - **`uploadFile` and `downloadFile` give the LLM access to the local filesystem** with the privileges of the user running the MCP server. The LLM can read any file the process can read (including `~/.ssh/id_*`, browser data, source trees, `.env` files) and write to any path it can write to (including `~/.ssh/authorized_keys`). The path arguments are not sandboxed because the tool's contract is "transfer arbitrary files".
  437. - **The MCP server runs locally over STDIO, but the LLM is not trusted.** STDIO only describes the transport — the *content* of tool arguments is chosen by the model, which can be steered by any untrusted text it ingests during the conversation.
  438. - **`# @password:` annotations are kept out of the LLM's context**, but they live in `~/.ssh/config` on disk. Anything that gives an attacker arbitrary local file read (see above) also exposes those passwords. The annotation only protects against the LLM seeing the password through the MCP protocol, not against local file disclosure.
  439. ### Recommendations
  440. - Run MCP SSH Agent under a **dedicated, unprivileged OS user** whose home directory only contains the SSH config and keys you actually want the LLM to be able to use.
  441. - Or run it inside a **container / sandbox** with a minimal `~/.ssh` and no access to other secrets on your machine.
  442. - Keep `~/.ssh/config` to the smallest set of hosts you trust the LLM with. Use restricted shell users on the remote side where possible.
  443. - Treat any session where the LLM ingests untrusted content (web pages, e‑mails, third‑party repos, other MCP servers' output) as potentially hostile to MCP SSH operations.
  444. - Report suspected vulnerabilities via GitHub's private vulnerability reporting on this repository.
  445. ## Security Best Practices
  446. ### SSH Key Security
  447. - **Never use password-protected keys** with MCP SSH Agent
  448. - **Never share private keys** - they should stay on your machine only
  449. - **Use Ed25519 keys** when possible (more secure than RSA)
  450. - **Create separate keys** for different environments/purposes
  451. - **Regularly rotate keys** (every 6-12 months)
  452. ### Server Security
  453. - **Disable password authentication** completely
  454. - **Use non-standard SSH ports** to reduce automated attacks
  455. - **Limit SSH access** to specific users with `AllowUsers`
  456. - **Choose appropriate root login policy**:
  457. - `PermitRootLogin prohibit-password` - Allows root access with SSH keys only (recommended for admin tasks)
  458. - `PermitRootLogin no` - Completely disables root login (most secure, but requires sudo access)
  459. - **Enable SSH key-only authentication** for all accounts
  460. - **Consider using jump hosts** for additional security layers
  461. ### Network Security
  462. - **Use VPN or bastion hosts** for production servers
  463. - **Implement fail2ban** to block brute force attempts
  464. - **Monitor SSH logs** regularly
  465. - **Use SSH key forwarding carefully** (disable when not needed)
  466. ## Building the MCP Bundle
  467. For developers who want to build the bundle locally:
  468. ### Prerequisites
  469. - Node.js 20 or higher
  470. - npm
  471. ### Building
  472. ```bash
  473. npm install
  474. npm run build:mcpb
  475. ```
  476. This writes `build/mcp-ssh-<version>.mcpb`, installable in Claude Desktop.
  477. The bundle is packed from a staging copy containing only production dependencies,
  478. so it does not carry the test and build toolchain. The build refuses to run if
  479. `manifest.json` and `package.json` disagree on the version.
  480. ### Publishing a release
  481. ```bash
  482. npm run build:mcpb
  483. gh release upload v1.3.9 build/mcp-ssh-1.3.9.mcpb
  484. ```
  485. ## Contributing
  486. Contributions are welcome! Please feel free to submit a Pull Request.
  487. ```bash
  488. npm install # also compiles src/ -> dist/ via the prepare script
  489. npm run build # tsc
  490. npm run typecheck # tsc --noEmit, strict for src/ and relaxed for tests
  491. npm run lint # eslint with type-aware rules
  492. npm test # vitest with coverage
  493. npm run test:watch # watch mode
  494. ```
  495. The server is written in TypeScript under `src/` and compiled to `dist/`, which is what
  496. `bin/mcp-ssh.js` loads and what ships to npm. `dist/` is not in git — a fresh checkout gets
  497. it from `npm install`.
  498. Three things to know before opening a PR:
  499. - **Coverage is a build gate.** `vitest.config.mjs` pins statements, branches, functions and
  500. lines of `src/` at 100%, so a change that adds an untested line fails CI. If a branch
  501. is genuinely unreachable, removing it is usually better than working around the threshold.
  502. - **Lint rules are calibrated, not stock.** Where a rule is relaxed, the reason is in a comment
  503. next to it. `prefer-nullish-coalescing` in particular exempts strings and numbers on purpose:
  504. `||` and `??` are *not* interchangeable for environment variables (a stripped launcher env
  505. reports an empty string, see issue #10) or for `timeout || DEFAULT`.
  506. - **CI runs on Linux and Windows** across Node 20, 22 and 24. Platform-specific code paths are
  507. tested from either OS by re-importing the module with `process.platform` faked — see
  508. `loadServerAs()` in `src/test-helpers.ts` — rather than by skipping tests on one platform.
  509. ## License
  510. MIT License - see LICENSE file for details.
  511. ## Project Structure
  512. ```
  513. mcp-ssh/
  514. ├── src/ # TypeScript sources
  515. │ ├── server.ts # Entry point: MCP server wiring and main()
  516. │ ├── tools.ts # Tool definitions and dispatch
  517. │ ├── ssh-client.ts # All ssh/scp operations
  518. │ ├── ssh-config-parser.ts # Host discovery from config and known_hosts
  519. │ ├── config-values.ts # ssh-config value normalization
  520. │ ├── platform.ts # Platform detection, binary resolution, logging
  521. │ ├── types.ts # Shared types
  522. │ └── server.test.ts # Test suite (vitest)
  523. ├── dist/ # Compiled output (generated, not in git)
  524. ├── bin/
  525. │ └── mcp-ssh.js # Executable entry point (loads dist/server.js)
  526. ├── tsconfig.json # Strict compiler options for src/
  527. ├── tsconfig.build.json # Build config (excludes tests)
  528. ├── tsconfig.test.json # Relaxed options for test files
  529. ├── eslint.config.mjs # typescript-eslint, type-aware rules
  530. ├── vitest.config.mjs # Test and coverage configuration
  531. ├── manifest.json # MCP Bundle manifest
  532. ├── package.json # Dependencies and scripts
  533. ├── README.md # Documentation
  534. ├── LICENSE # MIT License
  535. ├── CHANGELOG.md # Release history
  536. ├── PUBLISHING.md # Publishing instructions
  537. ├── .gitattributes # Forces LF checkout on every platform
  538. ├── start.sh # Development startup script
  539. ├── start-silent.sh # Silent startup script
  540. ├── scripts/
  541. │ └── build-mcpb.sh # MCP Bundle build script
  542. └── doc/ # Documentation assets
  543. ├── example.png # Usage example screenshot
  544. └── Claude.png # Claude Desktop integration example
  545. ```
  546. ## About
  547. This project is maintained by [aionda.com](https://aionda.com) and provides a reliable bridge between AI assistants and SSH infrastructure through the Model Context Protocol.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.