🚀 SSH MCP Server (Node.js)


A secure, high-performance Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop to execute SSH commands on remote servers. Built with Node.js and the official MCP SDK for maximum compatibility and reliability.

> 🔄 Version 2.1.0 - Token-Efficient File Operations: Complete rewrite in Node.js with official MCP SDK - eliminates all previous Go compatibility issues!

---

✨ Features

- 🔐 Secure SSH: Private key authentication with multiple key format support
- 🤖 AI-Ready: Official MCP SDK integration for Claude Desktop and other AI tools
- ⚡ High Performance: Node.js async architecture for fast command execution
- 📦 Zero Setup: One-command installation via NPX - no compilation required
- 🌐 Universal: Pure JavaScript runs on Windows, macOS, and Linux
- 🛡️ Type Safe: Built with modern JavaScript and comprehensive error handling
- 📋 Standards Compliant: Uses official @modelcontextprotocol/sdk

---

🚀 Quick Start

$3

``bash

Use directly with NPX (recommended)

npx @idletoaster/ssh-mcp-server@latest

Or install globally

npm install -g @idletoaster/ssh-mcp-server
`

$3

Add to your Claude Desktop MCP configuration file:

`json
{
"mcpServers": {
"ssh": {
"command": "npx",
"args": ["-y", "@idletoaster/ssh-mcp-server@latest"],
"env": {}
}
}
}
`

That's it! Claude can now execute SSH commands on your remote servers.

---

💬 Usage Examples

Once configured, Claude can help you with commands like:

> "Check disk usage on my production server at 192.168.1.100"

> "Restart the nginx service on server.example.com as user admin"

> "Show running processes on my Ubuntu server using my SSH key"

$3


`json
{
"tool": "remote-ssh",
"arguments": {
"host": "192.168.1.100",
"user": "ubuntu",
"command": "df -h",
"privateKeyPath": "/home/user/.ssh/id_rsa"
}
}
`

---

🔧 Configuration

$3

The server supports multiple authentication methods:

#### 1. Explicit Key Path
`json
{
"privateKeyPath": "/path/to/your/private/key"
}
`

#### 2. Environment Variable
`bash
export SSH_PRIVATE_KEY="/home/user/.ssh/id_rsa"
`

#### 3. Auto-Discovery
Automatically searches for keys in:
- ~/.ssh/id_rsa
- ~/.ssh/id_ed25519
- ~/.ssh/id_ecdsa

$3


- ✅ RSA keys (id_rsa)
- ✅ ED25519 keys (id_ed25519)
- ✅ ECDSA keys (id_ecdsa)
- ✅ OpenSSH format
- ✅ PEM format

---

🛠️ Development

$3

- Node.js 18+ (check: node --version)
- NPM 9+ (check: npm --version)

$3

#### Windows:
Download from nodejs.org or use Chocolatey:
`bash
choco install nodejs
`

#### Linux (Ubuntu/Debian):
`bash
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
`

#### Linux (CentOS/RHEL):
`bash
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs
`

#### macOS:
`bash
brew install node
`

$3


`bash

Clone repository

git clone https://github.com/idletoaster/ssh-mcp-server.git
cd ssh-mcp-server

Install dependencies

npm install

Run locally

npm start

Development with auto-reload

npm run dev
`

---

🏗️ Architecture

`
ssh-mcp-server/
├── package.json # NPM configuration & dependencies
├── index.js # Main MCP server (Official SDK)
├── lib/
│ └── ssh-client.js # SSH connection management
├── README.md # Documentation
├── LICENSE # MIT license
└── .gitignore # Node.js gitignore
`

$3

- Runtime: Node.js 18+ with ES Modules
- MCP SDK: @modelcontextprotocol/sdk (Official)
- SSH: ssh2 library for Node.js
- Distribution: NPM with direct NPX execution

---

🔒 Security

$3

- ✅ Private key authentication only (no passwords)
- ✅ Configurable SSH algorithms and timeouts
- ✅ No persistent connections (session-based)
- ✅ Input validation and sanitization
- ✅ Comprehensive error handling

$3

- 🔐 Store private keys with restrictive permissions (chmod 600)
- 🌐 Use SSH key passphrases when possible
- 🛡️ Restrict SSH keys to specific hosts in ~/.ssh/config
- 📝 Monitor SSH access logs
- 🚫 Never run as root unless absolutely necessary

$3

`bash

Example SSH config for restricted access

Host production-server
HostName 192.168.1.100
User deploy
IdentityFile ~/.ssh/production_key
IdentitiesOnly yes
StrictHostKeyChecking yes
`

---

🧪 Testing

$3

`bash

Test the MCP server

echo '{"host":"test.server.com","user":"testuser","command":"whoami"}' | npm start
`

$3

`bash

Verify Node.js installation

node --version # Should be 18+
npm --version # Should be 9+

Test NPX execution

npx @idletoaster/ssh-mcp-server@latest --help
`

---

🌍 Compatibility

$3

- ✅ Windows 10/11 (x64, ARM64)
- ✅ macOS 12+ (Intel & Apple Silicon)
- ✅ Linux (x64, ARM64) - All major distributions

$3

- 🤖 Claude Desktop (Primary target)
- 🤖 Cursor IDE
- 🤖 Any MCP-compatible application

$3

- ✅ Node.js 18.x (LTS)
- ✅ Node.js 20.x (LTS)
- ✅ Node.js 22.x (Current)

---

📊 Migration from v1.x (Go)

Upgrading from the Go version? The Node.js version offers:

$3

- Zero compilation - No more binary builds
- Better compatibility - Official MCP SDK
- Faster development - Direct code changes
- Simpler deployment - Pure NPX distribution
- No protocol issues - Official Anthropic SDK

$3

1. Uninstall old version: Remove Go-based installation
2. Install new version: npx @idletoaster/ssh-mcp-server@latest
3. Update Claude config: Same configuration works!
4. Test connection: Verify SSH functionality

---

🤝 Contributing

$3

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Test thoroughly: npm test
5. Submit a pull request

$3

- Use ES6+ modern JavaScript
- Follow Node.js best practices
- Add JSDoc comments for functions
- Validate with existing patterns

---

📄 License

MIT License - see LICENSE file for details.

---

🙏 Acknowledgments

- @modelcontextprotocol/sdk - Official MCP SDK
- ssh2 - Node.js SSH client
- Claude Desktop - Primary target platform
- Model Context Protocol - Standard specification

---

📞 Support

- 📋 Issues: GitHub Issues
- 💬 Discussions: GitHub Discussions

---

Built with ❤️ for the AI development community using Node.js and official MCP SDK

🆕 NEW in v2.1.0: Token-Efficient File Operations

Enhanced with 4 powerful tools inspired by Desktop Commander for optimal token usage:

$3

1. ssh-edit-block - Edit specific text blocks (80-90% token reduction vs full rewrites)
2. ssh-read-lines - Read file sections by line numbers (massive savings for large files)
3. ssh-search-code - Pattern search without reading full files
4. ssh-write-chunk - Efficient content writing with append/rewrite modes

$3

- 80-90% fewer tokens for file operations
- No more full file rewrites for small changes
- Partial file reading for large codebases
- Pattern searching without token overhead

$3

`javascript
// Edit specific text blocks
{
"name": "ssh-edit-block",
"arguments": {
"host": "server.com",
"user": "username",
"filePath": "/path/to/file.js",
"oldText": "version: '2.0.0'",
"newText": "version: '2.1.0'"
}
}

// Read specific lines only
{
"name": "ssh-read-lines",
"arguments": {
"host": "server.com",
"user": "username",
"filePath": "/path/to/large-file.js",
"startLine": 100,
"endLine": 150
}
}

// Search patterns efficiently
{
"name": "ssh-search-code",
"arguments": {
"host": "server.com",
"user": "username",
"path": "/project",
"pattern": "function.*export",
"filePattern": "*.js"
}
}
``